Get Features
The Features API provides features for ML Models across all types of demand causal factors, including attended events and non-attended events.
POST https://api.predicthq.com/v1/features/
Header | Value |
---|---|
Content-Type | Receive results in JSON or CSV by specifying the appropriate Content-Type header. Supported values:
|
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:
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:
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:
|
<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 } |
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 |
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:
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:
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 |
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 |
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:
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:
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 |
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:
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:
E.g. { "phq_rank": { "gt": 50, "lt": 80 } } |
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. |
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:
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 } } |
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 |