Features API

The Features API provides features for ML Models across all types of demand causal factors, including attended events and non-attended events.

It allows you to go straight to feature-importance testing and improving your models rather than having to worry about first building a data lake and then aggregating the data.

• Request category features

Features API is new and features will be expanded and added to over time. The endpoint currently supports:

• PHQ Attendance features (for attendance based events)

• PHQ Academic Attendance features (for academic attendance based events)

• PHQ Viewership features (for viewership based events)

• PHQ Rank features (for scheduled, non-attendance based events)

• PHQ Academic Rank features (for scheduled, academic based events)

• PHQ Impact features (for impact based events)

Basic Concepts

Every request to the API must specify which features are needed. Each request must specify a date range and location (that applies to all features in that request). Certain groups of features support additional filtering/parameters. Results are at the daily level.

Response Format

It is possible to specify the format of the response by passing the appropriate value in the Accept header, valid values are application/json or text/csv.

Range filter constraint

Each request can currently fetch up to 90 days worth - for longer date ranges, multiple requests must be made and we have some examples of how to do that in this notebook. There is no pagination in this API.

Common base and constraints

At minimum the following needs to be provided in the POST request:

• Active start date

• Active end date

• location - Geo-location and radius or list of placeId

These will apply globally across all requested features as the base filter criteria.

Range filter constraint

The calculated active data range may not exceed 90 days

Constraint on list of PlaceIDs

If more than 1 PlaceID is specified the response will detail the aggregated stats across the multiple (up to 3) PlaceID specified

Category Features

Each request to the Features API has to specify at least one or more category features. These features are currently based on attendance, viewership, rank or impact:

• see PHQ Attendance 

• see PHQ Viewership

• see PHQ Rank

• see PHQ Impact

Response

The Features API returns a timeseries response containing an entry for each day across the requested active date range for evaluation. The response structure for PHQ Attendance, and PHQ Viewership, differs from PHQ Rank in that the former return the calculated statistics requested based on PHQ Attendance/PHQ Viewership, and the latter returns a Rank range histogram of event counts.

PHQ Attendance response

Example response entry:

"phq_attendance_concerts": {
    "stats": {
        "count": 16,
        "sum": 4972
    }
}

The above is returned for each attendance category feature requested. The stats will contain the calculated values for all statistical measures requested in the criteria.

PHQ Viewership response

Example response entry:

"phq_viewership_sports_american_football_nfl": {
    "stats": {
        "count": 21,
        "sum": 5643
    }
}

The above is returned for each viewership category feature requested. The stats will contain the calculated values for all statistical measures requested in the criteria.

PHQ Rank response

Example response entry:

"phq_rank_public_holidays": {
    "rank_levels": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 2,
        "5": 0
    }
}

The above is returned for each rank category feature requested. The rank_levels will contain the calculated histogram of event counts based on rank range i.e.

• 0 <= phq-rank <= 20 → Rank-Level: 1

• 20 < phq-rank <= 40 → Rank-Level: 2

• 40 <= phq-rank <= 60 → Rank-Level: 3

• 60 <= phq-rank <= 80 → Rank-Level: 4

• 80 <= phq-rank <= 100 → Rank-Level: 5

Rank based Feature Fields

These fields aggregate events based on the specified scheduled, non-attendance based category, into different buckets of PHQ rank levels. An explicit feature key will be defined for each phq_rank_{rank based category} combination. Available fields:

• daylight-savings → phq_rank_daylight_savings

• health-warnings → phq_rank_health_warnings

• observances → phq_rank_observances

• public-holidays → phq_rank_public_holidays

• school-holidays → phq_rank_school_holidays

• politics → phq_rank_politics

• academic → see Academic Attendance Features

Note on specifying features

Rank features have no specific filter criteria at this time. They are only activated by setting the field valid to true

Impact based Feature Fields

These fields aggregate events based on their impact for a given industry vertical for a specified category and subcategory. Currently the only category supported is severe_weather and the only vertical is retail. Feature format: phq_impact_{category}_{subcategory}_{vertical}.

PHQ Academic Feature Fields

An explicit feature key will be defined for each {feature_type}_academic_{type} combination. There are 5 different academic {types} - namely:

• academic-session

• exam

• holiday

• graduation

• social

PHQ Academic Attendance

Aggregates PHQ attendance value for academic events based on the explicit type specified. Only graduation and social events are considered attendance based events. This will result in the following academic based feature keys conforming to the structure phq_attendance_academic_{type}:

• graduation → phq_attendance_academic_graduation

• social → phq_attendance_academic_social

The filter criteria remain the same as for phq_attendance_{category} features!

PHQ Academic Rank

Aggregates PHQ rank value for academic events based on the explicit type specified. Only academic-session, exam, and holiday are considered rank based events. This will result in the following academic based feature keys conforming to phq_rank_academic_{type}:

• academic-session → phq_rank_academic_session

• exam → phq_rank_academic_exam

• holiday → phq_rank_academic_holiday

The filter criteria remain the same as for phq_rank_{category} features i.e. there are none.

Base fields

Active Date Range Filter Fields

Supports gt, gte, lt, and lte constraints.

Validations:

• Requires both {gt|gte} and {lt|lte} to be specified.

• {gt|gte} value must be less than {lt|lte} value.

• Date range must be less or equal to 90 days.

• Minimum date is 2016-01-01

• Maximum date is {current year + 1}-12-31

Location Filter Fields

A location filter is required and this is done by specifying one of the following:

• Place filter defined by a list of Place IDs, or

• Geo-Distance filter

Place filter validations:

• Supports up to a maximum of three Place IDs

• Mutually exclusive with Geo-Distance filter field

GEO-DISTANCE FILTER FIELDS

A filter based on geo-point and distance from, defining a Latitude: {lat}, Longitude: {lon} and Radius: {radius}.

Validations:

• -90 <= Latitude <= 90

• -180 <= Longitude <= 180

• Radius cannot exceed 100 miles or equivalent

• allowed units for radius : km, mi, m, ft

PHQ Attendance Criteria Fields

Defines the desired statistical measures to be processed and returned as well as provide the means to define a rank filter

The PHQ Attendance criteria is based on the PHQ Statistical Criteria, this may be specifically extended for attendance in the future.

PHQ Viewership Criteria Fields

Defines the desired statistical measures to be processed and returned as well as provide the means to define a rank filter

The PHQ Viewership criteria is based on the PHQ Statistical Criteria, this may be specifically extended for viewership in the future.

PHQ Base Statistical Criteria Fields

Defines the base fields for processing of statistical features.

• an optional list of aggregation functions applied to the phq_attendance/phq_viewership value. Validations:

  • count and sum are the default stats being included in the response.

  • Other available functions include: min, max, avg, median and std_dev.

• a optional phq_rank based filter - see PHQ Rank Filter

PHQ Rank Filter

PHQ rank filter. Supports gt, gte, lt, and lte constraints.

Validations:

• {gt|gte} constraint value must be less than {lt|lte} constraint value.

• Minimum rank is 0

• Maximum rank is 100 

Filtering on start and end times

This functionality is currently only available for viewership features. Additional features will be supported in the future. Time of day filters can be used to narrow down on viewership aggregations that are relevant to your hours of operation and other day-parted analyses. To use time of day filters, the hour_of_day_start section must be populated with a time range between 0 - 23, corresponding to hours in a 24h time format. Only whole numbers are currently supported.

Example of hour of the day filtering.

POST /v1/features/ HTTP/1.1
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

{
    "active": {
        "gte": "2019-12-16",
        "lte": "2020-01-30"
    },
    "hour_of_day_start": {
        "gte": 13,
        "lte": 15
    },
    "location": {
        "place_id": [
            "6252001"
        ]
    },
    "phq_viewership_sports_american_football": {
        "stats": [
            "count",
            "std_dev",
            "median"
        ],
        "phq_rank": {
            "gt": 50
        }
    },
    "phq_viewership_sports_american_football_ncaa_men": true,
    "phq_viewership_sports_american_football_nfl": true
}