Links

Get Features

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

Request

HTTP Request

POST https://api.predicthq.com/v1/features/

Request Headers

Header
Value
Content-Type
Receive results in JSON or CSV by specifying the appropriate Content-Type header.
Supported values:
  • application/json
  • text/csv

Request Body

Field
Description
active object
The date range to calculate features for. This is named "active" because it includes events that are active within the date range. A multi-day event might start or end outside the specified date range - the days the event is active within the specified range will be included in the calculations.
Supports the following fields:
  • gt - greater than
  • gte - greater than or equal
  • lt - less than
  • lte - less than or equal
Note that all dates here are in local time (not UTC). Features API works on specific locations.
Please also note that the maximum supported date range is 90 days. If you require features over a wider date range please make multiple API requests.
E.g.
{
"active": {
"gte": "2019-11-28",
"lte": "2019-11-29"
}
}
hour_of_day_start object
Time range (per day) to calculate features for.
Note: This field is currently only supported on phq_viewership_* features.
If your location only operates within certain hours of the day you can use this filter to only include records that are happening within those hours.
Supports the following fields:
  • gt - greater than
  • gte - greater than or equal
  • lt - less than
  • lte - less than or equal
The values are hours between 0 and 23 (i.e. 24h format).
E.g. only include events happening between 1pm and 3pm each day.
{
"hour_of_day_start": {
"gte": 13,
"lte": 15
}
}
location object
Location to calculate features for. You can specify the location as a latitude/longitude (with radius), Place ID or Saved Location ID.
We recommend using a lat/lon+radius so your location can be more accurately defined, and we strongly recommend using our Suggested Radius API to work out a suitable radius around your location.
Note, when using Place IDs or Saved Location IDs a maximum of 3 IDs may be used.
E.g. using Place IDs.
{
"location": {
"place_id": [
5224323,
5811704,
4887398
]
}
}
E.g. using Saved Location IDs.
{
"location": {
"saved_location_id": [
"BN7ZSw8xza9FviPVfyCycd",
"X3uyTFbDOUaX2q_Qh5i31b",
"X3uyTFbDOUhrfq_Qh5i31A"
]
}
}
E.g. using a latitude/longitude and radius (recommended)
{
"location": {
"geo": {
"lat": 41.75038,
"lon": -71.49978,
"radius": "2.6mi"
}
}
}
The radius is in the format: <radius><radius_unit>
Supported radius units are:
  • m - meters
  • km - kilometers
  • ft - feet
  • mi - miles
<feature_name> object or boolean
The name of the feature you're requesting. You can request multiple features in a single request. Features can be further configured here, or you can set the value as true to perform the default calculations for that feature. Please see the tables below for a list of all currently supported features and how they can be further configured.
E.g. requesting certain stats fields and filtering for records with a PHQ Rank over 50.
{
"phq_attendance_sports": {
"stats": ["count", "std_dev", "median"],
"phq_rank": {
"gt": 50
}
}
}
E.g. requesting the default calculations for a feature.
{
"phq_attendance_concerts": true
}

Available Features

PHQ Attendance Features
PHQ Rank Features
PHQ Viewership Features
PHQ Impact Features
PHQ Attendance features provide daily-level aggregated stats based on the number of people who we predict will attend events on a given day. This takes into account complications like distributing attendance across multi-day events.
Feature
Description
phq_attendance_academic_graduation
Academic - Graduation
phq_attendance_academic_social
Academic - Social
phq_attendance_community
Community
phq_attendance_concerts
Concerts
phq_attendance_conferences
Conferences
phq_attendance_expos
Expos
phq_attendance_festivals
Festivals
phq_attendance_performing_arts
Performing Arts
phq_attendance_sports
Sports
phq_attendance_school_holidays
School Holidays

Configuration

You can configure PHQ Attendance features using the options below.
Field
Description
stats object optional
You can optionally configure which fields are calculated for each of these features by providing the list of stats fields you would like.
Default fields are count and sum.
Supported fields are:
  • count
  • sum
  • min
  • max
  • avg
  • median
  • std_dev
E.g.
{
"stats": [
"count",
"std_dev",
"median"
]
}
phq_rank object optional
Filter for events with a PHQ Rank within a certain range.
Supports the following fields:
  • gt - greater than
  • gte - greater than or equal
  • lt - less than
  • lte - less than or equal
E.g.
{
"phq_rank": {
"gt": 50,
"lt": 80
}
}
PHQ Rank features provide daily-level aggregated sum of events bucketed by PHQ Rank level (1-5).
Feature
Description
phq_rank_observances
Observances
phq_rank_public_holidays
Public Holidays
phq_rank_school_holidays
School Holidays
phq_rank_academic_session
Academic - Session
phq_rank_academic_exam
Academic - Exam
phq_rank_academic_holiday
Academic - Holiday

Configuration

PHQ Rank features cannot currently be configured further. When requesting phq_rank_* features set the value as true indicating you require the default calculations.
PHQ Viewership features provide daily-level aggregated stats based on the number of people who we predict will view broadcasts on a given day.
Feature
Description
phq_viewership_sports
Sports - (All)
phq_viewership_sports_american_football
American Football - (All)
phq_viewership_sports_american_football_ncaa_men
American Footbal - NCAA Men's
phq_viewership_sports_american_football_nfl
American Football - NFL
phq_viewership_sports_auto_racing
Automotive Racing - All
phq_viewership_sports_auto_racing_indy_car
Automotive Racing - Indy Car
phq_viewership_sports_auto_racing_nascar
Automotive Racing - NASCAR
phq_viewership_sports_baseball
Baseball - (All)
phq_viewership_sports_baseball_mlb
Baseball - MLB
phq_viewership_sports_baseball_ncaa_men
Baseball - NCAA Men's
phq_viewership_sports_basketball
Basketball - (All)
phq_viewership_sports_basketball_nba
Basketball - NBA
phq_viewership_sports_basketball_ncaa_men
Basketball - NCAA Men's
phq_viewership_sports_basketball_ncaa_women
Basketball - NCAA Women's
phq_viewership_sports_boxing
Boxing - (All)
phq_viewership_sports_golf
Golf - (All)
phq_viewership_sports_golf_masters
Golf - Masters
phq_viewership_sports_golf_pga_championship
Golf - PGA Championships
phq_viewership_sports_golf_pga_tour
Golf - PGA Tours
phq_viewership_sports_golf_us_open
Golf - US Open
phq_viewership_sports_horse_racing
Horse Racing - (All)
phq_viewership_sports_horse_racing_belmont_stakes
Horse Racing - Belmont Stakes
phq_viewership_sports_horse_racing_kentucky_derby
Horse Racing - Kentucky Derby
phq_viewership_sports_horse_racing_preakness_stakes
Horse Racing - Preakness Stakes
phq_viewership_sports_ice_hockey
Ice Hockey - (All)
phq_viewership_sports_ice_hockey_nhl
Ice Hockey - NHL
phq_viewership_sports_mma
Mixed Martial Arts - (All)
phq_viewership_sports_mma_ufc
Mixed Martial Arts - UFC
phq_viewership_sports_soccer
Soccer - (All)
phq_viewership_sports_soccer_concacaf_champions_league
Soccer - CONCACAF Champions League
phq_viewership_sports_soccer_concacaf_gold_cup
Soccer - CONCACAF Gold Cup
phq_viewership_sports_soccer_copa_america_men
Soccer - COPA America Men's
phq_viewership_sports_soccer_fifa_world_cup_women
Soccer - FIFA World Cup Women's
phq_viewership_sports_soccer_fifa_world_cup_men
Soccer - FIFA World Cup Men's
phq_viewership_sports_soccer_mls
Soccer - MLS
phq_viewership_sports_soccer_uefa_champions_league_men
Soccer - UEFA Champions League Men's
phq_viewership_sports_softball
Softball - (All)
phq_viewership_sports_softball_ncaa_women
Softball - NCAA Women's
phq_viewership_sports_tennis
Tennis - (All)
phq_viewership_sports_tennis_us_open
Tennis - US Open
phq_viewership_sports_tennis_wimbledon
Tennis - Wimbledon

Configuration

You can configure PHQ Attendance features using the options below.
Field
Description
stats object optional
You can optionally configure which fields are calculated for each of these features by providing the list of stats fields you would like.
Default fields are count and sum.
Supported fields are:
  • count
  • sum
  • min
  • max
  • avg
  • median
  • std_dev
E.g.
{
"stats": [
"count",
"std_dev",
"median"
]
}
phq_rank object optional
Filter for events with a PHQ Rank within a certain range.
Supports the following fields:
  • gt - greater than
  • gte - greater than or equal
  • lt - less than
  • lte - less than or equal
E.g.
{
"phq_rank": {
"gt": 50,
"lt": 80
}
}
PHQ Impact features provide daily-level aggregated stats based on the predicted impact of an event. This takes into account complications like Impact Patterns (leading and lagging effects of an event). Currently supported industries are: Retail.
Feature
Description
Industry
phq_impact_severe_weather_air_quality_retail
Severe Weather - Air Quality
Retail
phq_impact_severe_weather_blizzard_retail
Severe Weather - Blizzard
Retail
phq_impact_severe_weather_cold_wave_retail
Severe Weather - Cold Wave - (All)
Retail
phq_impact_severe_weather_cold_wave_snow_retail
Severe Weather - Cold Wave - Snow
Retail
phq_impact_severe_weather_cold_wave_storm_retail
Severe Weather - Cold Wave - Storm
Retail
phq_impact_severe_weather_dust_retail
Severe Weather - Dust - (All)
Retail
phq_impact_severe_weather_dust_storm_retail
Severe Weather - Dust - Storm
Retail
phq_impact_severe_weather_flood_retail
Severe Weather - Flood
Retail
phq_impact_severe_weather_heat_wave_retail
Severe Weather - Heat Wave
Retail
phq_impact_severe_weather_hurricane_retail
Severe Weather - Hurricane
Retail
phq_impact_severe_weather_thunderstorm_retail
Severe Weather - Thunderstorm
Retail
phq_impact_severe_weather_tornado_retail
Severe Weather - Tornado
Retail
phq_impact_severe_weather_tropical_storm_retail
Severe Weather - Tropical Storm
Retail

Configuration

You can configure PHQ Impact features using the options below.
Field
Description
stats object optional
You can optionally configure which fields are calculated for each of these features by providing the list of stats fields you would like.
Default fields are count and sum.
Supported fields are:
  • count
  • sum
  • min
  • max
  • avg
  • median
  • std_dev
E.g.
{
"stats": [
"count",
"std_dev",
"median"
]
}
phq_rank object optional
Filter for events with a PHQ Rank within a certain range.
Supports the following fields:
  • gt - greater than
  • gte - greater than or equal
  • lt - less than
  • lte - less than or equal
E.g.
{
"phq_rank": {
"gt": 50,
"lt": 80
}
}

Response

Response Fields

Field
Description
results array
List of results where each item is a Feature.
Please refer to the Feature Response Fields section below for the structure of each record. Note that pagination is not required in this API.

Feature Response Fields

Other than the date, the structure of each result here will depend on how you configured the feature in your request and the type of feature.
PHQ Attendance Features
PHQ Rank Features
PHQ Viewership Features
PHQ Impact Features
Field
Description
date string
Date in local time. E.g. 2023-10-01
<phq_attendance_*> object
Daily-level feature result. The structure of the result here will depend on how you configured the feature in your request.
PHQ Attendance features are stats-based.
Default fields are count and sum.
E.g.
{
"stats": {
"count": 5,
"sum": 17307,
"min": 1000,
"max": 9215,
"avg": 3461.4,
"median": 2620.0,
"std_dev": 2978.810473997968
}
}
Field
Description
date string
Date in local time. E.g. 2023-10-01
<phq_rank_*> object
Daily-level feature result. The structure of the result here is always the same as PHQ Rank features cannot currently be configured.
Will contain a rank_levels field which indicates the sum of matching events active on the date at each PHQ Rank level.
PHQ Rank is on a scale of 0 to 100 and the levels are bucketed as:
  • 1 - Minor (rank between 0 and 20).
  • 2 - Moderate (rank between 21 and 40).
  • 3 - Important (rank between 41 and 60).
  • 4 - Significant (rank between 61 and 80).
  • 5 - Major (rank between 81 and 100).
E.g.
{
"rank_levels": {
"1": 0,
"2": 0,
"3": 0,
"4": 2,
"5": 0
}
}
Field
Description
date string
Date in local time. E.g. 2023-10-01
<phq_viewership_*> object
Daily-level feature result. The structure of the result here will depend on how you configured the feature in your request.
PHQ Viewership features are stats-based.
Default fields are count and sum.
E.g.
{
"stats": {
"count": 5,
"sum": 17307,
"min": 1000,
"max": 9215,
"avg": 3461.4,
"median": 2620.0,
"std_dev": 2978.810473997968
}
}
Field
Description
date string
Date in local time. E.g. 2023-10-01
<phq_impact_*> object
Daily-level feature result. The structure of the result here will depend on how you configured the feature in your request.
PHQ Impact features are stats-based.
Default fields are count and sum.
E.g.
{
"stats": {
"count": 5,
"sum": 17307,
"min": 1000,
"max": 9215,
"avg": 3461.4,
"median": 2620.0,
"std_dev": 2978.810473997968
}
}

Response Format

You can receive responses formatted as JSON (default) or CSV. Use the Content-Type header when performing your request to define which format you would like to receive.
JSON
CSV
With the Content-Type header set to application/json you will receive the results as JSON like the example below:
{
"results": [
{
"date": "2019-11-16",
"phq_attendance_concerts": {
"stats": {
"count": 20,
"sum": 6751
}
},
"phq_attendance_conferences": {
"stats": {
"min": 1500,
"max": 1500
}
},
"phq_attendance_sports": {
"stats": {
"count": 5,
"sum": 17307,
"min": 1000,
"max": 9215,
"avg": 3461.4,
"median": 2620.0,
"std_dev": 2978.810473997968
}
},
"phq_rank_public_holidays": {
"rank_levels": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
}
}
},
{
"date": "2019-11-17",
"phq_attendance_concerts": {
"stats": {
"count": 2,
"sum": 241
}
},
"phq_attendance_conferences": {
"stats": {
"min": 67,
"max": 67
}
},
"phq_attendance_sports": {
"stats": {
"count": 1,
"sum": 852,
"min": 852,
"max": 852,
"avg": 852.0,
"median": 852.0,
"std_dev": 0.0
}
},
"phq_rank_public_holidays": {
"rank_levels": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
}
}
}
]
}
With the Content-Type header set to text/csv you will receive the results as CSV like the example below:
date,phq_attendance_concerts_stats_count,phq_attendance_concerts_stats_sum,phq_attendance_conferences_stats_min,phq_attendance_conferences_stats_max,phq_attendance_sports_stats_count,phq_attendance_sports_stats_sum,phq_attendance_sports_stats_min,phq_attendance_sports_stats_max,phq_attendance_sports_stats_avg,phq_attendance_sports_stats_median,phq_attendance_sports_stats_std_dev,phq_rank_public_holidays_rank_levels_1,phq_rank_public_holidays_rank_levels_2,phq_rank_public_holidays_rank_levels_3,phq_rank_public_holidays_rank_levels_4,phq_rank_public_holidays_rank_levels_5
2019-11-16,43,24546,11,1000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-17,25,13440,11,146,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-18,6,2021,11,700,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-19,10,6047,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-20,14,59704,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-21,21,60851,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-22,35,25760,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-23,29,25425,11,394,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-24,18,23410,11,500,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-25,6,5122,11,1000,1,18064,18064,18064,18064.0,18064.0,0.0,0,0,0,0,0
2019-11-26,8,6861,11,1000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-27,12,6225,11,500,1,18064,18064,18064,18064.0,18064.0,0.0,0,0,0,0,0
The same data represented as a table:
date
phq_attendance_concerts_stats_count
phq_attendance_concerts_stats_sum
phq_attendance_conferences_stats_min
phq_attendance_conferences_stats_max
phq_attendance_sports_stats_count
phq_attendance_sports_stats_sum
phq_attendance_sports_stats_min
phq_attendance_sports_stats_max
phq_attendance_sports_stats_avg
phq_attendance_sports_stats_median
phq_attendance_sports_stats_std_dev
phq_rank_public_holidays_rank_levels_1
phq_rank_public_holidays_rank_levels_2
phq_rank_public_holidays_rank_levels_3
phq_rank_public_holidays_rank_levels_4
phq_rank_public_holidays_rank_levels_5
2019-11-16
43
24546
11
1000
0
0
0
0
0.0
0.0
0
0
0
0
0
2019-11-17
25
13440
11
146
0
0
0
0
0.0
0.0
0
0
0
0
0
2019-11-18
6
2021
11
700
0
0
0
0
0.0
0.0
0
0
0
0
0
2019-11-19
10
6047
11
171000
0
0
0
0
0.0
0.0
0
0
0
0
0
2019-11-20
14
59704
11
171000
0
0
0
0
0.0
0.0
0
0
0
0
0
2019-11-21
21
60851
11
171000
0
0
0
0
0.0