Introducing the Forecasts API — Event-driven forecasts for precise demand planning. Fast, accurate, and easy to run.
Explore Now
LogoLogo
Visit websiteWebAppGet DemoTry for Free
  • Introduction
  • Swagger UI
  • Loop
  • System Status
  • Getting Started
    • API Quickstart
    • Data Science Notebooks
    • PredictHQ Data
      • Data Accuracy
      • Event Categories
        • Attendance-Based Events
        • Non-Attendance-Based Events
        • Unscheduled Events
        • Live TV Events
      • Labels
      • Entities
      • Ranks
        • PHQ Rank
        • Local Rank
        • Aviation Rank
      • Predicted Attendance
      • Predicted End Times
      • Predicted Event Spend
      • Predicted Events
      • Predicted Impact Patterns
    • Guides
      • Geolocation Guides
        • Overview
        • Searching by Location
          • Find Events by Latitude/Longitude and Radius
          • Find Events by Place ID
          • Find Events by IATA Code
          • Find Events by Country Code
          • Find Events by Placekey
          • Working with Location-Based Subscriptions
        • Understanding Place Hierarchies
        • Working with Polygons
        • Join Events using Placekey
      • Date and Time Guides
        • Working with Recurring Events
        • Working with Multi-day and Umbrella Events
        • Working with Dates, Times and Timezones
      • Events API Guides
        • Understanding Relevance Field in Event Results
        • Attendance-Based Events Notebooks
        • Non-Attendance-Based Events Notebooks
        • Severe Weather Events Notebooks
        • Academic Events Notebooks
        • Working with Venues Notebook
      • Features API Guides
        • Increase Accuracy with the Features API
        • Get ML Features
        • Demand Forecasting with Event Features
      • Forecasts API Guides
        • Getting Started with Forecasts API
        • Understanding Forecast Accuracy Metrics
        • Troubleshooting Guide for Forecasts API
      • Live TV Event Guides
        • Find Broadcasts by County Place ID
        • Find Broadcasts by Latitude and Longitude
        • Find all Broadcasts for an Event
        • Find Broadcasts for Specific Sport Types
        • Aggregating Live TV Events
        • Live TV Events Notebooks
      • Beam Guides
        • ML Features by Location
        • ML Features by Group
      • Demand Surge API Guides
        • Demand Surge Notebook
      • Guide to Protecting PredictHQ Data
      • Streamlit Demo Apps
      • Guide to Bulk Export Data via the WebApp
      • Industry-Specific Event Filters
      • Tutorials
        • Filtering and Finding Relevant Events
        • Improving Demand Forecasting Models with Event Features
        • Using Event Data in Power BI
        • Using Event Data in Tableau
        • Connecting to PredictHQ APIs with Microsoft Excel
        • Loading Event Data into a Data Warehouse
        • Displaying Events in a Heatmap Calendar
        • Displaying Events on a Map
    • Tutorials by Use Case
      • Demand Forecasting with ML Models
      • Dynamic Pricing
      • Inventory Management
      • Workforce Optimization
      • Visualization and Insights
  • Integrations
    • Integration Guides
      • Keep Data Updated via API
      • Integrate with Beam
      • Integrate with Loop Links
    • Third-Party Integrations
      • Receive Data via Snowflake
        • Example SQL Queries for Snowflake
        • Snowflake Data Science Guide
          • Snowpark Method Guide
          • SQL Method Guide
      • Receive Data via AWS Data Exchange
        • CSV/Parquet Data Structure for ADX
        • NDJSON Data Structure for ADX
      • Integrate with Databricks
      • Integrate with Tableau
      • Integrate with a Demand Forecast in PowerBI
      • Google Cloud BigQuery
    • PredictHQ SDKs
      • Python SDK
      • Javascript SDK
  • API Reference
    • API Overview
      • Authenticating
      • API Specs
      • Rate Limits
      • Pagination
      • API Changes
      • Attribution
      • Troubleshooting
    • Events
      • Search Events
      • Get Event Counts
    • Broadcasts
      • Search Broadcasts
      • Get Broadcasts Count
    • Features
      • Get ML Features
    • Forecasts
      • Models
        • Create Model
        • Update Model
        • Replace Model
        • Delete Model
        • Search Models
        • Get Model
        • Train Model
      • Demand Data
        • Upload Demand Data
        • Get Demand Data
      • Forecasts
        • Get Forecast
      • Algorithms
        • Get Algorithms
    • Beam
      • Create an Analysis
      • Upload Demand Data
      • Search Analyses
      • Get an Analysis
      • Update an Analysis
      • Partially Update an Analysis
      • Get Correlation Results
      • Get Feature Importance
      • Refresh an Analysis
      • Delete an Analysis
      • Analysis Groups
        • Create an Analysis Group
        • Get an Analysis Group
        • Search Analysis Groups
        • Update an Analysis Group
        • Partially Update an Analysis Group
        • Refresh an Analysis Group
        • Delete an Analysis Group
        • Get Feature Importance for an Analysis Group
    • Demand Surge
      • Get Demand Surges
    • Suggested Radius
      • Get Suggested Radius
    • Saved Locations
      • Create a Saved Location
      • Search Saved Locations
      • Get a Saved Location
      • Search Events for a Saved Location
      • Update a Saved Location
      • Delete a Saved Location
    • Loop
      • Loop Links
        • Create a Loop Link
        • Search Loop Links
        • Get a Loop Link
        • Update a Loop Link
        • Delete a Loop Link
      • Loop Settings
        • Get Loop Settings
        • Update Loop Settings
      • Loop Submissions
        • Search Submitted Events
      • Loop Feedback
        • Search Feedback
    • Places
      • Search Places
      • Get Place Hierarchies
  • WebApp Support
    • WebApp Overview
      • Using the WebApp
      • API Tools
      • Events Search
      • How to Create an API Token
    • Getting Started
      • Can I Give PredictHQ a Go on a Free Trial Basis?
      • How Do I Get in Touch if I Need Help?
      • Using AWS Data Exchange to Access PredictHQ Events Data
      • Using Snowflake to Access PredictHQ Events Data
      • What Happens at the End of My Free Trial?
      • Export Events Data from the WebApp
    • Account Management
      • Managing your Account Settings
      • How Do I Change My Name in My Account?
      • How Do I Change My Password?
      • How Do I Delete My Account?
      • How Do I Invite People Into My Organization?
      • How Do I Log In With My Google or LinkedIn Account?
      • How Do I Update My Email Address?
      • I Signed Up Using My Google/LinkedIn Account, but I Want To Log In With My Own Email
    • API Plans, Pricing & Billing
      • Do I Need To Provide Credit Card Details for the 14-Day Trial?
      • How Do I Cancel My API Subscription?
      • Learn About Our 14-Day Trial
      • What Are the Definitions for "Storing" and "Caching"?
      • What Attribution Do I Have To Give PredictHQ?
      • What Does "Commercial Use" Mean?
      • What Happens If I Go Over My API Plan's Rate Limit?
    • FAQ
      • How Does PredictHQ Support Placekey?
      • Using Power BI and Tableau With PredictHQ Data
      • Can I Download a CSV of Your Data?
      • Can I Suggest a New Event Category?
      • Does PredictHQ Have Historical Event Data?
      • Is There a PredictHQ Mobile App?
      • What Are Labels?
      • What Countries Do You Have School Holidays For?
      • What Do The Different Event Ranks Mean?
      • What Does Event Visibility Window Mean?
      • What Is the Difference Between an Observed Holiday and an Observance?
    • Tools
      • Is PHQ Attendance Available for All Categories?
      • See Event Trends in the WebApp
      • What is Event Trends?
      • Live TV Events
        • What is Live TV Events?
        • Can You Access Live TV Events via the WebApp?
        • How Do I Integrate Live TV Events into Forecasting Models?
      • Labels
        • What Does the Closed-Doors Label Mean?
    • Beam (Relevancy Engine)
      • An Overview of Beam - Relevancy Engine
      • Creating an Analysis in Beam
      • Uploading Your Demand Data to Beam
      • Viewing the List of Analysis in Beam
      • Viewing the Table of Results in Beam
      • Viewing the Category Importance Information in Beam
      • Feature Importance With Beam - Find the ML Features to Use in Your Forecasts
      • Beam Value Quantification
      • Exporting Correlation Data With Beam
      • Getting More Details on a Date on the Beam Graph
      • Grouping Analyses in Beam
      • Using the Beam Graph
      • Viewing the Time Series Impact Analysis in Beam
    • Location Insights
      • An Overview of Location Insights
      • How to Set a Default Location
      • How Do I Add a Location?
      • How Do I Edit a Location?
      • How Do I Share Location Insights With My Team?
      • How Do I View Details for One Location?
      • How Do I View My Saved Locations as a List?
      • Search and View Event Impact in Location Insights
      • What Do Each of the Columns Mean?
      • What Is the Difference Between Center Point & Radius and City, State, Country?
Powered by GitBook

PredictHQ

  • Terms of Service
  • Privacy Policy
  • GitHub

© 2025 PredictHQ Ltd

On this page
  • Request
  • HTTP Request
  • Request Headers
  • Query Parameters
  • Request Body
  • Available Features
  • Response
  • Response Fields
  • Response Format
  • Examples
  • Guides

Was this helpful?

  1. API Reference
  2. Features

Get ML Features

Prebuilt intelligence for Machine Learning models.

Access prebuilt Machine Learning features that will take your forecast models and results to the next level, fast. Gain access to over 100 ML-ready features that are guaranteed to improve your forecasting accuracy.

Request

HTTP Request

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

Request Headers

Header
Value

Accept

Receive results in JSON or CSV by specifying the appropriate Accept header.

Supported values:

  • application/json

  • text/csv

Query Parameters

Parameter
Description

offset number

The number of results to skip. The default is 0.

E.g. ?offset=20

limit number

The maximum number of results to return per page.

The default limit is 100 and the maximum per page is 100.

E.g. ?limit=10

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.

beam object

An optional beam analysis object which if provided will calculate the location, interval, week_start_day , phq_* features including stats and phq_rank from the Beam analysis and optionally the Beam analysis group.

Supports the following fields:

  • analysis_id - Beam analysis id (Required if beam block is present in the request body)

  • group_id - Beam analysis group id (Optional)

If beam.analysis_id is provided, the location, interval, week_start_day , phq_* features includingstats and phq_rank will be calculated from the Beam analysis.

E.g.

If both beam.analysis_id and beam.group_id are provided, all the above fields will be calculated from the Beam analysis but the phq_* features will be calculated from the Beam analysis Group.

Note: This is useful for when you want to request features for a variety of locations while maintaining feature consistency by limiting the returned features to those of the group's feature importance results.

E.g.

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.

location object

Note: When using Place IDs or Saved Location IDs a maximum of 3 IDs may be used.

Note: When using lat/lon+radius, the radius must be in the format <radius><radius_unit>, where <radius> is an integer or a float number up to 2 decimal places and <radius_unit> is one of:

  • m - meters

  • km - kilometers

  • ft - feet

  • mi - miles

E.g. using Place IDs:

E.g. using Saved Location IDs:

E.g. using a latitude/longitude and radius (recommended):

interval string optional

Aggregation interval. Possible values:

  • day (default) for daily aggregation

  • week for weekly aggregation

week_start_day string optional

The weekday to be treated as the start of the week.

Possible values:

  • monday (default)

  • tuesday

  • wednesday

  • thursday

  • friday

  • saturday

  • sunday

Only applicable when interval is set to week.

predicted_events object

optional

Include or Exclude predicted events. Supports the following fields:

  • exclude Possible values:

    • true

    • false(default) Include predicted events

E.g.

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

E.g. requesting the default calculations for a feature.

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

We recommend using impact pattern features instead of generic features if you are in one of the supported industries. See #attended-events-impact-patterns.

Attended Events Generic Features

Use the generic features in this table if you are not in one of the industries covered by the impact pattern features listed below.

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

Attended Events Impact Pattern Features

Predicted Impact Patterns model the impact of leading days (days before the event), lagging days (days after an event), and the days the event occurs. In the Features API, Impact Patterns are provided as different features with a feature per industry. We have impact pattern features for the accommodation, hospitality (which covers food & beverage including restaurants), and retail industries.

The features above are generic features and the features in the table below are the impact pattern features per industry. For example, if you were in the accommodation industry and wanted a feature for the conferences category you'd use phq_attendance_conferences_accommodation.

We recommend using impact pattern features instead of generic features if you are in one of the supported industries. See Predicted Impact Patterns for more details.

Feature
Description

phq_attendance_community_accommodation

Community accommodation impact

phq_attendance_concerts_accommodation

Concerts accommodation impact

phq_attendance_conferences_accommodation

Conferences accommodation impact

phq_attendance_expos_accommodation

Expos accommodation impact

phq_attendance_festivals_accommodation

Festivals accommodation impact

phq_attendance_performing_arts_accommodation

Performing Arts accommodation impact

phq_attendance_sports_accommodation

Sports accommodation impact

phq_attendance_community_hospitality

Community hospitality impact

phq_attendance_concerts_hospitality

Concerts hospitality impact

phq_attendance_conferences_hospitality

Conferences hospitality impact

phq_attendance_expos_hospitality

Expos hospitality impact

phq_attendance_festivals_hospitality

Festivals hospitality impact

phq_attendance_performing_arts_hospitality

Performing Arts hospitality impact

phq_attendance_sports_hospitality

Sports hospitality impact

phq_attendance_community_retail

Community Retail impact

phq_attendance_concerts_retail

Concerts Retail impact

phq_attendance_conferences_retail

Conferences Retail impact

phq_attendance_expos_retail

Expos Retail impact

phq_attendance_festivals_retail

Festivals Retail impact

phq_attendance_performing_arts_retail

Performing Arts Retail impact

phq_attendance_sports_retail

Sports Retail impact

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.

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.

local_rank object optional

Filter for events with a Local 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 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).

Holidays and Observances Impact Pattern Features

These features include the Predicted Impact Patterns for public holidays and observances. For example, these features will show when people typically arrive and book accommodation before a holiday and if they tend to leave after the holiday. See Predicted Impact Patterns

We recommend that if you operate in the industries listed below you use the demand impact features for holidays and observances instead of the generic features as these will result in greater forecast accuracy as they include the impact before an event starts and after it finishes.

Feature
Category
Industry

phq_impact_public_holidays

Public Holidays

N/A

phq_impact_public_holidays_accommodation

Public Holidays

Accomodation

phq_impact_public_holidays_hospitality

Public Holidays

Hospitality/Food & Beverage*

phq_impact_public_holidays_retail

Public Holidays

Retail

phq_impact_observances

Observances

N/A

phq_impact_observances_accommodation

Observances

Accomodation

phq_impact_observances_retail

Observances

Retail

phq_impact_observances_hospitality

Observances

Hospitality/Food & Beverage

phq_impact_school_holidays

School Holidays

N/A

phq_impact_academic_exam

Academic

N/A

phq_impact_academic_holiday

Academic

N/A

phq_impact_academic_session

Academic

N/A

Severe Weather Impact Features

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

Attended Events Impact Features

See #attended-events-impact-pattern-features

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.

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.

local_rank object optional

Filter for events with a Local 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 Spend features provide daily-level aggregated stats based on total USD we predict will be spent during events on a given day. This takes into account complications like distributing attendance across multi-day events.

You can request industry-specific features which are tuned to one of three potential industries:

  • Accommodation: Event spend relating to hotels and hosts for the purposes of staying at during events. Spend can extend before and after an event actually starts/ends.

  • Hospitality: Event spend on restaurants, food and drinks. Hotel restaurants are included in this industry.

  • Transportation: Ground-based transportation for the purposes of getting to and from an event. Includes public and private transport, such as taxis, rails, busses and rideshares.

Feature
Description

phq_spend_conferences

Conferences

phq_spend_expos

Expos

phq_spend_sports

Sports

phq_spend_community

Community

phq_spend_concerts

Concerts

phq_spend_festivals

Festivals

phq_spend_performing_arts

Performing Arts

phq_spend_conferences_accommodation

Conferences - Accommodation

phq_spend_expos_accommodation

Expos - Accommodation

phq_spend_sports_accommodation

Sports - Accommodation

phq_spend_community_accommodation

Community - Accommodation

phq_spend_concerts_accommodation

Concerts - Accommodation

phq_spend_festivals_accommodation

Festivals - Accommodation

phq_spend_performing_arts_accommodation

Performing Arts - Accommodation

phq_spend_conferences_hospitality

Conferences - Hospitality

phq_spend_expos_hospitality

Expos - Hospitality

phq_spend_sports_hospitality

Sports - Hospitality

phq_spend_community_hospitality

Community - Hospitality

phq_spend_concerts_hospitality

Concerts - Hospitality

phq_spend_festivals_hospitality

Festivals - Hospitality

phq_spend_performing_arts_hospitality

Performing Arts - Hospitality

phq_spend_conferences_transportation

Conferences - Transportation

phq_spend_expos_transportation

Expos - Transportation

phq_spend_sports_transportation

Sports - Transportation

phq_spend_community_transportation

Community - Transportation

phq_spend_concerts_transportation

Concerts - Transportation

phq_spend_festivals_transportation

Festivals - Transportation

phq_spend_performing_arts_transportation

Performing Arts - Transportation

Configuration

You can configure PHQ Spend 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.

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.

local_rank object optional

Filter for events with a Local 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 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.

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.

local_rank object optiona

Filter for events with a Local 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 features provide the daily-level aggregated sum of events bucketed by PHQ Rank level (1-5).

PHQ Rank Impact Pattern Features

See the "Holidays and Observances Impact Pattern Features" under PHQ Impact in the tab above. These features cover the Accommodation, Retail, and Hospitality (Food & Beverage) industries.

We recommend that if you operate in the supported industries you use the demand impact features for holidays and observances instead of the generic features as these will result in greater forecast accuracy as they include the impact before an event starts and after it finishes.

PHQ Rank Generic Features

These are generic features that do not include Predicted Impact Patterns and should be used if you are not in one of the industries that we have impact patterns for.

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_daylight_savings

Daylight savings

phq_rank_health_warnings

Health Warnings

phq_rank_politics

Politics

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.

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.

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.

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.

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.

Field
Description

date string

Date in local time. E.g. 2023-10-01

<phq_spend_*> object

Daily-level feature result. The structure of the result here will depend on how you configured the feature in your request.

PHQ Spend features are stats-based.

Default fields are count and sum.

E.g.

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.

Response Format

You can receive responses formatted as JSON (default) or CSV. Use the Accept header when performing your request to define which format you would like to receive.

With the Accept 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 Accept 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

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

Examples

curl -X POST "https://api.predicthq.com/v1/features/?offset=0&limit=100" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data @<(cat <<EOF
    {
        "active": {
            "gte": "2019-11-16",
            "lte": "2019-11-17"
        },
        "location": {
            "geo": {
                "lat": "37.78428",
                "lon": "-122.40075",
                "radius": "2.6mi"
            }
        },
        "phq_attendance_conferences": {
            "stats": [
                "min",
                "max"
            ]
        },
        "phq_attendance_sports": {
            "stats": ["count", "std_dev", "median"],
            "phq_rank": { 
                "gt": 50
            }    
        },
        "phq_attendance_concerts": true,
        "phq_rank_public_holidays": true
    }
    EOF
    )
import requests

data = {
    "active": {
        "gte": "2019-11-16",
        "lte": "2019-11-27"
    },
    "location": {
        "geo": {
            "lat": "37.78428",
            "lon": "-122.40075",
            "radius": "2.6mi"
        }
    },
    "phq_attendance_conferences": {
        "stats": [
            "min",
            "max"
        ]
    },
    "phq_attendance_sports": {
        "stats": ["count", "std_dev", "median"],
        "phq_rank": { 
            "gt": 50
        }    
    },
    "phq_attendance_concerts": True,
    "phq_rank_public_holidays": True
}

response = requests.post(
    url="https://api.predicthq.com/v1/features/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
      "offset": 0,
      "limit": 100
    },
    json=data
)

print(response.json())
from predicthq import Client

phq = Client(access_token="$ACCESS_TOKEN")

for feature in phq.features.obtain_features(
        active__gte="2019-11-16",
        active__lte="2019-11-27",
        location__geo={
            "lat": "37.78428",
            "lon": "-122.40075",
            "radius": "2.6mi"
        },
        phq_attendance_conferences__stats=["min", "max"],
        phq_attendance_sports__stats=["count", "std_dev", "median"],
        phq_attendance_sports__phq_rank={
            "gt": 50
        },
        phq_attendance_concerts=True,
        phq_rank_public_holidays=True
):
    print(feature.date, feature.phq_attendance_conferences.stats.min, 
        feature.phq_attendance_conferences.stats.max,
        feature.phq_attendance_sports.stats.count,
        feature.phq_attendance_sports.stats.std_dev,
        feature.phq_attendance_sports.stats.median,
        feature.phq_attendance_concerts.stats.count,
        feature.phq_attendance_concerts.stats.sum,
        feature.phq_rank_public_holidays.rank_levels)

Guides

Below are some guides relevant to this API:

  • Increase Accuracy with the Features API

  • Get ML Features

  • Demand Forecasting with Event Features

  • Aggregating Live TV Events

PreviousFeaturesNextForecasts

Last updated 1 month ago

Was this helpful?

Location to calculate features for. You can specify the location as a latitude/longitude (with radius), Place ID(s) or ID(s).

We recommend using a lat/lon+radius or a saved location id (for a point and radius location) as they could define the location of your interest more accurately. To work out a suitable radius around your location we strongly recommend using our .

{
  "active": {
    "gte": "2019-11-28",
    "lte": "2019-11-29"
  }
}
{
  "beam": {
    "analysis_id": "0SXAmHsoZo0"
  }
}
{
  "beam": {
    "analysis_id": "0SXaMHsoYo0",
    "group_id": "QxE9BcLq7ZY"
  }
}
{
  "hour_of_day_start": {
    "gte": 13,
    "lte": 15
  }
}
{
  "location": {
    "place_id": [
      5224323,
      5811704,
      4887398
    ]
  }
}
{
  "location": {
    "saved_location_id": [
      "BN7ZSw8xza9FviPVfyCycd",
      "X3uyTFbDOUaX2q_Qh5i31b",
      "X3uyTFbDOUhrfq_Qh5i31A"
    ]
  }
}
{
  "location": {
    "geo": {
      "lat": 41.75038,
      "lon": -71.49978,
      "radius": "2.62mi"
    }
  }
}
{
  "predicted_events": {
    "exclude": false
  }
}
{
  "phq_attendance_sports": {
    "stats": ["count", "std_dev", "median"],
    "phq_rank": { 
      "gt": 50
    }
  }
}
{
  "phq_attendance_concerts": true
}
{
  "stats": [
    "count",
    "std_dev",
    "median"
  ]
}
{
  "phq_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "local_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "stats": [
    "count",
    "std_dev",
    "median"
  ]
}
{
  "phq_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "local_rank": {
    "gt": 50,
    "lt": 80
  }
{
  "stats": [
    "count",
    "std_dev",
    "median"
  ]
}
{
  "phq_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "local_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "stats": [
    "count",
    "std_dev",
    "median"
  ]
}
{
  "phq_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "local_rank": {
    "gt": 50,
    "lt": 80
  }
}
{
  "stats": {
    "count": 5,
    "sum": 17307,
    "min": 1000,
    "max": 9215,
    "avg": 3461.4,
    "median": 2620.0,
    "std_dev": 2978.810473997968
  }
}
{
  "stats": {
    "count": 5,
    "sum": 17307,
    "min": 1000,
    "max": 9215,
    "avg": 3461.4,
    "median": 2620.0,
    "std_dev": 2978.810473997968
  }
}
{
  "rank_levels": {
    "1": 0,
    "2": 0,
    "3": 0,
    "4": 2,
    "5": 0
  }
}
{
  "stats": {
    "count": 5,
    "sum": 17307,
    "min": 1000,
    "max": 9215,
    "avg": 3461.4,
    "median": 2620.0,
    "std_dev": 2978.810473997968
  }
}
{
  "stats": {
    "count": 5,
    "sum": 17307,
    "min": 1000,
    "max": 9215,
    "avg": 3461.4,
    "median": 2620.0,
    "std_dev": 2978.810473997968
  }
}
Saved Location
Suggested Radius API