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.

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

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.

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 or rank:

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 differs from PHQ Rank in that the former returns the calculated statistics requested based on PHQ Attendance, 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.0
    }
}

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 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

Request Features

Attendance based Feature Fields

These fields aggregate PHQ attendance value for events based on the specified attendance based category. An explicit feature key will be defined for each phq_attendance_{attendance based category} combination! i.e.

  • communityphq_attendance_community
  • concertsphq_attendance_concerts
  • conferencesphq_attendance_conferences
  • exposphq_attendance_expos
  • festivalsphq_attendance_festivals
  • performing-artsphq_attendance_performing_arts
  • sportsphq_attendance_sports
  • academicsee Academic Attendance Features

Note on specifying features

If a category feature is not explicitly requested it WILL NOT be queried or evaluated

Field

Description

phq_attendance_community bool or Attendance Criteria optional excluded by default

Attendance community feature.

Example 1: "phq_attendance_community": true

Example 2: "phq_attendance_community": {"stats":..., "phq_rank": {...}}

phq_attendance_concerts bool or Attendance Criteria optional excluded by default

Attendance concerts feature.

Example 1: "phq_attendance_concerts": true

Example 2: "phq_attendance_concerts": {"stats":..., "phq_rank": {...}}

phq_attendance_conferences bool or Attendance Criteria optional

Attendance conferences feature.

Example 1: "phq_attendance_conferences": true

Example 2: "phq_attendance_conferences": {"stats":..., "phq_rank": {...}}

phq_attendance_expos bool or Attendance Criteria optional excluded by default

Attendance expos feature.

Example 1: "phq_attendance_expos": true

Example 2: "phq_attendance_expos": {"stats":..., "phq_rank": {...}}

phq_attendance_festivals bool or Attendance Criteria optional excluded by default

Attendance festivals feature.

Example 1: "phq_attendance_festivals": true

Example 2: "phq_attendance_festivals": {"stats":..., "phq_rank": {...}}

phq_attendance_performing_arts bool or Attendance Criteria optional excluded by default

Attendance performing-arts feature.

Example 1: "phq_attendance_performing_arts": true

Example 2: "phq_attendance_performing_arts": {"stats":., "phq_rank": {.}}

phq_attendance_sports bool or Attendance Criteria optional excluded by default

Attendance sports feature.

Example 1: "phq_attendance_sports": true

Example 2: "phq_attendance_sports": {"stats":..., "phq_rank": {...}}

Each feature category can have differing Attendance Criteria except for active date and location as this is defined globally.

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! i.e.

  • daylight-savingsphq_rank_daylight_savings
  • health-warningsphq_rank_health_warnings
  • observancesphq_rank_observances
  • public-holidaysphq_rank_public_holidays
  • school-holidaysphq_rank_school_holidays
  • politicsphq_rank_politics
  • academicsee 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

Field

Description

phq_rank_daylight_savings bool optional excluded by default

Rank daylight-savings feature. To activate set to true.

E.g. "phq_rank_daylight_savings": true

phq_rank_health_warnings bool optional excluded by default

Rank health-warnings feature. To activate set to true.

E.g. "phq_rank_health_warnings": true

phq_rank_observances bool optional excluded by default

Rank observances feature. To activate set to true.

E.g. "phq_rank_observances": true

phq_rank_public_holidays bool optional excluded by default

Rank public-holidays feature. To activate set to true.

E.g. "phq_rank_public_holidays": true

phq_rank_school_holidays bool optional excluded by default

Rank school-holidays feature. To activate set to true.

E.g. "phq_rank_school_holidays": true

phq_rank_politics bool optional excluded by default

Rank politics feature. To activate set to true.

E.g. "phq_rank_politics": true

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}:

  • graduationphq_attendance_academic_graduation
  • socialphq_attendance_academic_social

Field

Description

phq_attendance_academic_graduation bool or Attendance Criteria optional excluded by default

Attendance academic graduation feature.

Example 1: "phq_attendance_academic_graduation": true

Example 2: "phq_attendance_academic_graduation": {....}

phq_attendance_academic_social bool or Attendance Criteria optional excluded by default

Attendance academic social feature.

Example 1: "phq_attendance_academic_social": true

Example 2: "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-sessionphq_rank_academic_session
  • examphq_rank_academic_exam
  • holidayphq_rank_academic_holiday

Field

Description

phq_rank_academic_session bool optional excluded by default

Rank academic session-savings feature. To activate set to true.

E.g. "phq_rank_academic_session": true

phq_rank_academic_exam bool optional excluded by default

Rank academic exam feature. To activate set to true.

E.g. "phq_rank_academic_exam": true

phq_rank_academic_holiday bool optional excluded by default

Rank academic holidays feature. To activate set to true.

E.g. "phq_rank_academic_holiday": true

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

Field

Description

gt string optional

Filter for Active local date > Date - ISO 8601 format.

E.g. 2014-07-16

gte string optional

Filter for Active local date >= Date - ISO 8601 format.

E.g. 2014-07-16

lt string optional

Filter for Active local date < Date - ISO 8601 format.

E.g. 2014-07-16

lte string optional

Filter for Active local date <= Date - ISO 8601 format.

E.g. 2014-07-16

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

Filter required

Either a place_id or a geo filter criteria have to be defined!

Place filter validations:

Field

Description

place_id string optional* Mutually exclusive with geo

A comma-separated list of place ids (see Places)

E.g. all events that apply to the State of New York: "place_id": [5128638]

geo object optional* Mutually exclusive with place_id

Filter for geo-location and radius

E.g. "lon": -71.49978, "lat": 41.75038, "radius": "30mi"

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

Field

Description

lat number required

Latitude value

E.g. "lat": 41.75038

lon number required

Longitude value

E.g. "lon": -71.49978

radius string required

Radius measure and unit value

E.g. "radius": "50km" or "radius: "10mi" or "radius": "200m"

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 consists of:

  • an optional list of aggregation functions applied to the phq_attendance 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

Field

Description

stats list of string optional* *count and sum are processed by default

List of desired stats to be processed

E.g. “stats": ["count", "min", "max”]

phq_rank object optional

Filter for PHQ Rank

E.g. “phq_rank":{"gt": 50, "lt", 80}

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

Field

Description

gt integer optional

Filter for phq_rank >

E.g. "gt": 65

gte integer optional

Filter for phq_rank >=

E.g. "gte": 50

lt integer optional

Filter for phq_rank <

E.g. "lt": 90

lte integer read-only

Filter for phq_rank <=

E.g. "lte": 88