Events

The Events API gives you a read-only interface to PredictHQ's event data. An event represents something happening at a specific date, time and location, which is either scheduled or unscheduled.

New Data Sources

As PredictHQ evolves and develops, we will continue to provide more event categories as more sources become available.

If you're interested in a category that is not listed here or would like to see a specific data source added, drop us a line.

Features in Beta

For sport around 80% or more of source events data don’t have a known end time. The Predicted End Times feature uses machine learning and our intelligent algorithms to predict end times for events.

The initial beta release of Predicted End Times is for sports events. The Predicted End Times feature is only available to selected beta customers, please contact us if you would like to participate in the beta.


Search Events

Use the below parameters to search and filter all events that are available to your account.

Visibility Window

Please note that you will not receive an error when requesting a date range that is outside of your subscription's event visibility window.

However, your event visibility window will be automatically applied to your results.

Result Limit

Please note the count of your search results will be limited to your subscription's result limit. If more results exist the field overflow will be set to true to indicate it is being capped.

Parameters

Parameter

Description

active.* date range

The date from and/or to the events intersect with. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

E.g. ?active.gte=2015-01-01&active.lte=2015-03-01

aviation_rank.* rank range

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

Note when filtering on aviation_rank events that do not have an aviation_rank will not be returned.

E.g. ?aviation_rank.gte=80&aviation_rank.lte=90

aviation_rank_level number

A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ Aviation Rank levels.

Possible values:

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

Note when filtering on aviation_rank_level events that do not have an aviation_rank will not be returned.

E.g. ?aviation_rank_level=4,5

brand_unsafe.* brand-unsafe

Whether or not to exclude potentially brand-unsafe events. Potentially brand-unsafe events are included by default.

Currently only supports the exclude suffix.

  • exclude: whether or not to exclude potentially brand-unsafe events from results (required, valid options are true or false)

Examples of brand-unsafe events include content that promotes hate, violence or discrimination, coarse language, content that is sexually suggestive or explicit, etc.

Please note that use of a suffix is required.

E.g. ?brand_unsafe.exclude=true

cancelled.*

date range

The date from and/or to the event was set to cancelled in the system. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

Note when filtering on cancelled events that are not cancelled will not be returned.

E.g. ?cancelled.gte=2020-03-01&cancelled.lte=2020-03-15

category string

A comma-separated list of categories.

Possible values:

  • school-holidays
  • public-holidays
  • observances
  • politics
  • conferences
  • expos
  • concerts
  • festivals
  • performing-arts
  • sports
  • community
  • daylight-savings
  • airport-delays
  • severe-weather
  • disasters
  • terror

E.g. ?category=school-holidays,public-holidays

country string

A comma-separated list of country codes.

E.g. ?country=AU,NZ

deleted_reason string

A comma-separated list of deleted reasons for the events.

Possible values:

  • cancelled
  • invalid
  • duplicate
  • postponed

E.g. ?deleted_reason=cancelled,duplicate

end.* date range

The date from and/or to the event ends. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

E.g. ?end.gte=2018-12-19&end.lte=2018-12-19

end_around.* date around

Fuzzy date search around event end. Supports origin, offset, scale, decay suffixes.

  • origin: The date (required)
  • offset: The number of days from the origin before the score starts to decay (optional, defaults to 0d)
  • scale: Distance from origin +/- offset at which the score will equal the decay value (optional, defaults to 3d)
  • decay: Score value at the scale distance (optional, defaults to 0.5)

Can influence relevance.

E.g. ?end_around.origin=2018-12-19

entity.id string

A comma-separated list of entity identifiers.

E.g. ?entity.id=XABWvihQAj8TnjvF6WNzLW

id string

A comma-separated list of event identifiers.

E.g. ?id=z13B3870YOgv

label string

A comma-separated list of labels. Use the count endpoint to fetch a list of available labels.

E.g. ?label=holiday,observance

limit number

The maximum number of results to return. The default limit is 10.

E.g. ?limit=10

local_rank.* rank range

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

Note when filtering on local_rank events that do not have a local_rank will not be returned.

E.g. ?local_rank.gte=80&local_rank.lte=90

local_rank_level number

A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ local rank levels.

Possible values:

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

Note when filtering on local_rank_level events that do not have a local_rank will not be returned.

E.g. ?local_rank_level=4,5

location_around.* location around

Fuzzy location search around event location.

Please note this affects the relevance value and does not restrict search results to the specified latitude/longitude and offset. Read more in the Relevance guide and combine with the within parameter to restrict results to a specified latitude/longitude and radius.

Supports origin, offset, scale, decay suffixes.

  • origin: The location in the form {latitude},{longitude} (required)
  • offset: The distance before decay is applied (optional, defaults to 0km) (Distance unit can be one of m, km, ft, mi)
  • scale: Distance from origin + offset at which the score will equal decay value (optional, defaults to 2km) (Distance unit can be one of m, km, ft, mi)
  • decay: Score value at scale value (optional, defaults to 0.5)

E.g. ?location_around.origin=40.730610,-73.935242

offset number

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

E.g. ?offset=20

phq_attendance.* number range

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

E.g. ?phq_attendance.gte=2000&phq_attendance.lte=10000

place.* place

A comma-separated list of place ids (see Places) and/or IATA (3 character), ICAO (4 character), and UN/LOCODE (5 character) airport codes where the events occur. Supports scope or exact suffixes. Download CSV list of all supported airport codes and their respective place ids.

When place.scope is used, results will contain events that apply to the parent and children places of the specified place. E.g. National, regional and local school holidays that apply to a region.

When place.exact is used, results will contain events that apply to the specified place only. E.g. Regional school holidays only.

Please note that use of a suffix is required.

E.g.

  • all events that apply to the State of New York: ?place.scope=5128638
  • all events that apply to the place associated with San Francisco Airport: ?place.scope=SFO

postponed.*

date range

The date from and/or to the event was set to postponed in the system. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

Note when filtering on postponed events that are not postponed will not be returned.

E.g. ?postponed.gte=2020-03-01&postponed.lte=2020-03-15

predicted_end.* date range

Beta feature

Please note that this feature is currently in beta and only available to customers enrolled in the beta program.

The date from and/or to the event predicted_end. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

Note when filtering on predicted_end events that do not have a predicted_end will not be returned.

E.g. ?predicted_end.gte=2018-12-19&predicted_end.lte=2018-12-19

q string

A full-text search query.

Can influence relevance.

E.g. ?q=katy+perry

rank.* rank range

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

E.g. ?rank.gte=80&rank.lte=90

rank_level number

A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ rank levels.

Possible values:

  • 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_level=4,5

relevance string

A comma-separated list of components to include when calculating the relevance field of an event. The relevance components are multiplied together to produce the overall relevance.

Parameter Components: These components correspond to search parameters that can influence relevance. If the parameter isn't provided as part of a search its component will be ignored. By default, relevance includes the components of each relevance-influencing parameter in a search.

  • q
  • start_around
  • end_around
  • location_around

Field Components: These components correspond to event fields that can be included in relevance. They are not included in relevance by default.

  • rank
  • local_rank
  • aviation_rank

E.g. ?relevance=q,rank,location_around

sort string

A comma-separated list of fields to sort results by. The default is relevance,-start.

Prefix the field name with - for reverse order.

Possible values:

  • id
  • title
  • start
  • end
  • predicted_end (beta feature)
  • updated
  • rank
  • local_rank
  • aviation_rank
  • category
  • duration
  • country
  • labels
  • relevance

Note when sorting on predicted_end, local_rank or aviation_rank (regardless of sort order), events that do not have a predicted_end, local_rank or aviation_rank will be placed last.

When sorting by relevance the most relevant results are sorted first, regardless of sort order.

E.g. ?sort=country,-start

start.* date range

The date from and/or to the event starts. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

E.g. ?start.gte=2018-12-19&start.lte=2018-12-19

start_around.* date around

Fuzzy date search around event start. Supports origin, offset, scale, decay suffixes.

  • origin: The date (required)
  • offset: The number of days from the origin before the score starts to decay (optional, defaults to 0d)
  • scale: Distance from origin +/- offset at which the score will equal the decay value (optional, defaults to 3d)
  • decay: Score value at the scale distance (optional, defaults to 0.5)

Can influence relevance.

E.g. ?start_around.origin=2018-12-19

state string

A comma-separated list of states for the events. Supports active and deleted. By default, returns active events only.

This parameter is useful in conjunction with updated when you cache events and are interested in retrieving a list of all events that have changed since a specific date and time

E.g. ?state=active,deleted

updated.* date range

The date from and/or to the event was last modified. Supports gt, gte, lt, lte and tz suffixes.

Please note that use of a suffix is required.

E.g. ?updated.gte=2018-05-01T09:55:00Z

within area

A geo center and radius in the form {radius}{unit}@{latitude},{longitude}, where the radius unit can be one of: m, km, ft, mi.

Note that results may contain events that apply to a parent scope of the specified area.

E.g. National school holidays that apply to the local radius.

E.g. ?within=10km@-36.844480,174.768368


Event Fields

Below are the fields returned by the Events endpoint. Please note that these are not the fields used for filtering - please refer to the Search Events section to discover which parameters can be used for filtering events.

JSON Schemas are available for the Events endpoint and for a single event:

Field

Description

aviation_rank number, null read-only

A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. Aviation Rank indicates how much an event will impact flight bookings by considering both domestic and international travel. It can be mapped to the predicted increase in demand based on people flying to an event. Therefore, events with higher Aviation Rank are expected to result in more people taking flights than lower Aviation Rank events.

Aviation Rank is calculated for events in the categories concerts, conferences, expos, sports, festivals, performing-arts, observances, public-holidays, and school-holidays.

If aviation_rank is not intended to be available for an event or we couldn't calculate it, this field will be null.

E.g. 85

cancelled

string, null

read-only

The date the event was set to cancelled in the system in ISO 8601 format.

All dates are in UTC.

This field will only be present for events with deleted_reason set to cancelled, and will have a null value if cancelled date is not available.

E.g. 2018-12-19T10:00:00Z

category string read-only

The category of the event

Possible values:

  • school-holidays
  • public-holidays
  • observances
  • politics
  • conferences
  • expos
  • concerts
  • festivals
  • performing-arts
  • sports
  • community
  • daylight-savings
  • airport-delays
  • severe-weather
  • disasters
  • terror

E.g. concerts

country string read-only

The country code in ISO 3166-1 alpha-2 format.

E.g. NZ

deleted_reason string read-only

The reason why the event was deleted.

Note that this field is only present for events with state deleted.

Possible values:

  • cancelled
  • duplicate
  • invalid
  • postponed

E.g. duplicate

description string read-only

A description of the event.

E.g. See Katy Perry in concert [...]

duplicate_of_id string read-only

The id of the active event this event is a duplicate of.

Note that this field is only present for deleted events with deleted_reason set to duplicate.

E.g. z13B3870YOgv

duration number read-only

The duration of the event in seconds.

E.g. 3600

end string read-only

The end date of the event in ISO 8601 format.

All end dates are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the time zone, and will have a null time zone.

E.g. 2018-12-19T10:00:00Z

entities array read-only

An array of entities linked to the event.

Possible types:

  • venue

E.g. [{"entity_id": "328DxFUbRKvaiJJGyT2gReF", "type": "venue", "name": "Spark Arena", "formatted_address": "Mahuhu Crescent\nAuckland 1010\nNew Zealand"}]

first_seen string, null

read-only

The date the event first entered our dataset in ISO 8601 format. All dates are in UTC. This value may be missing on some events, and should not be considered an event announcement date.

E.g. 2017-12-19T06:00:00Z

id string read-only

The unique identifier of the event.

E.g. z13B3870YOgv

labels array read-only

The labels associated with the event. Use the count endpoint to fetch a list of available labels.

E.g. ["holiday", "holiday-national"]

local_rank number, null read-only

Similar to PHQ Rank, this is a log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event on its local geographical area.

Local Rank is calculated for events in the categories community, concerts, conferences, expos, sports, festivals, performing-arts.

If local_rank is not intended to be available for an event, this field will be null.

E.g. 72

location array read-only

A 2-tuple representing the geo location of the event. Note that the longitude/latitude coordinates use the GeoJSON order [lon, lat].

E.g. [174.776792, -36.847319]

phq_attendance number

read-only

A numerical value that reflects the predicted attendance number for supported attendance-based categories. The following categories are supported: concerts, performing arts, sports, expos, conferences, community and festivals.

E.g. 2511

place_hierarchies array read-only

An array of place hierarchies for the event. Each hierarchy is an array of place ids (see Places). The final place in a hierarchy is a specific place the event applies to. Each place is a sub-place of the place immediately preceding it in the hierarchy.

For example, a hierarchy might contain the following places in this order: Earth > Europe > United Kingdom > England > Nottingham

E.g. [["6295630", "6255148", "2635167", "6269131", "3333178", "2641170"]]

postponed

string, null

read-only

The date the event was set to postponed in the system in ISO 8601 format.

All dates are in UTC.

This field will only be present for events with deleted_reason set to postponed, and will have a null value if postponed date is not available.

E.g. 2018-12-19T10:00:00Z

predicted_end string

read-only

Beta feature

Please note that this feature is currently in beta and only available to customers enrolled in the beta program.

The predicted end date of the event in ISO 8601 format.

Predicted end dates are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the time zone, and will have a null time zone.

This field will only be present if an actual end time is not available for an event and we have a predicted end time.

E.g. 2018-12-19T10:00:00Z

rank number

read-only

A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event independent of its geographical location.

E.g. 83

relevance number, null read-only

Relative relevance of the event to the event search.

See the relevance parameter for information on how relevance is calculated.

E.g. 2.9654586

scope string read-only

The geographical scope the events apply to.

Possible values:

  • locality
  • county
  • region
  • country

E.g. locality

start string read-only

The start date of the event in ISO 8601 format.

All start dates are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the time zone, and will have a null time zone.

If an event has a start time of midnight (in the event time zone) this is an indication that the actual time may be unknown. You may wish to omit the time when displaying these events.

E.g. 2018-12-19T06:00:00Z

state string read-only

The publication state of the event.

Possible values:

  • active: the event is published and valid.
  • deleted: the event was removed, either because it was cancelled or is a duplicate.

timezone string, null read-only

The time zone of the event in TZ Database format. This is helpful so you know which time zone to convert the dates to (if needed).

If the time zone is null, the start and end date should be regarded as time zone agnostic and already being in local time. Our start and end filters take this into account when specifying a lower and higher bound on dates.

E.g. Pacific/Auckland

title string read-only

The title of the event.

E.g. Katy Perry

updated string

read-only

The last modification date of the event in ISO 8601 format. All dates are in UTC.

E.g. 2018-05-01T05:00:00Z


Retrieve Events Count

This endpoint accepts the same parameters as the ones described in Search Events and can be used to get aggregated counts of all matching events that are available to your account.

A JSON Schema is available for the Events Count endpoint: events_count.schema.json


Retrieve Events Calendar

This endpoint accepts the same parameters as the ones described in Search Events and can be used to get a calendar view of all matching events that are available to your account.

Each day in the calendar contains aggregate counts of all active events for that day.

A JSON Schema is available for the Events Calendar endpoint: events_calendar.schema.json


Retrieve Aggregate Event Impact

This feature can be used to find the correlation between your demand and the events data.

Because PHQ RankTM and Aviation Rank are log scale numerical values, simply summing up all the ranks does not deliver a meaningful result. PredictHQ’s Aggregate Event Impact tool does this calculation for you.

It provides the Aggregate Event Impact endpoint, which can be used to find a correlation between events and your historical demand data. This correlation is the first step in many different types of analyses, including demand forecasting and dynamic pricing.

It can be used for PHQ Rank or Aviation Rank. PHQ Rank uses factors like attendance information, venue size and related factors to calculate impact, whereas Aviation Rank identifies an event’s impact on airline demand.

Use the impact_rank parameter to specify the rank to use for calculating the aggregate impact and any of the parameters described in Search Events for filtering the events set.

Recommended filter parameters for Aggregate Event Impact

When using the Aggregate Event Impact endpoint you should specify a location either as a latitude and longitude and radius or as a place id. A common use case is to look at the impact of events in a city, but you can choose whatever location makes sense for your use case. You need to also specify a date range. You can use the active.gte and active.lte parameters (or other date range parameters) to specify the date range.

When dealing with aggregate impact based on PHQ Rank, we also recommend that you start by calling the endpoint to filter for events with a PHQ Rank or Local Rank of greater than or equal to 50 to filter out noise that can be caused by smaller events with a lower rank. E.g. rank.gte=50 or local_rank.gte=50. When you operate a business in a small to medium sized town or city you can use local rank to look at events which drive local demand close to a point (latitude/longitude) such as a store or hotel. PHQ Rank is generally applicable to looking at the overall size of events where the local impact is less important.

Aggregate Event Impact only applies to specific events categories

The categories are those for which we expect physical movements of people to and from a venue e.g. a stadium or theatre. This consists of events from the following categories: concerts, performing arts, sports, expos, conferences, community and festivals.

The impact figure does not include impact for the non-attendance-based event categories of public-holidays, school-holidays and observances. Events in these categories are shown in the categories field in the response for a given date. For example if there are 4 public-holidays events on a given day then the categories field will show a count of 4 for public-holidays. We suggest using dummy explanatory variables for the events in these holidays categories in your model. The suggested logic is to look if there is a holiday event on a given day or in a time period based on the count in the categories field and if it is present to set your dummy variable to 1, if there are no holidays then it should be 0.

Events without any impact, including events from non relevant categories, are not displayed in the Aggregate Event Impact endpoint results.

The endpoint returns a calendar view of the aggregate impacts of the events that are available to your account. Each day in the calendar contains aggregate counts of all active events and the sum of their impacts for that day. These values are further aggregated by rank levels and categories.

The count values use the active date range of an event. If an event active date range spans multiple days then the daily buckets count values will be incremented for each day the event spans. For example where an event starts on 2018-11-26 and ends on 2018-11-30 if you query for a range from 2018-11-26 to 2018-11-30 then the daily count will show this event for all the days in the aggregation. This means the top level count figure is not always the sum of the counts for all the individual days because sometimes the same event is included in the count of multiple days.

Active date range limit

Please note that a maximum active date range of 31 days applies. To specify the active date range you need to use the active parameter with a from (gt or gte) and a to (lt or lte) value.

E.g. ?active.gte=2019-01-20&active.lte=2019-01-22.

Parameters

The Aggregate Event Impact endpoint accepts the same parameters as described in Search Events except the id filter. Filters specific to this endpoint as noted below also applies.

Parameter

Description

impact_rank number

The rank to use for calculating the aggregate impact.

Please note that this parameter is required.

Possible values:

  • rank
  • aviation_rank

E.g. ?impact_rank=rank

Aggregate Event Impact Fields

Below are the fields returned by the Aggregate Event Impact endpoint. These results return values per day for all events matching the parameters supplied in the call to the endpoint. The endpoint also returns an overall count value that is a count of all results.

A JSON Schema is available for the Aggregate Event Impact endpoint: events_impact.schema.json

Field

Description

categories object read-only

A map of the categories supported by the endpoint and its count. For each category the value returned is a count of events in that category for the given day that match the parameters of the call to the endpoint. The count is of type number.

The count value includes the holiday categories of public-holidays, school-holidays and observances. These categories are not included in the overall impact value but the count is returned so it can be used for demand forecasting for example by using a dummy variable/binary variable for holiday impact.

E.g. {"community": 39, "concerts": 41, "conferences": 3, "expos": 1, "festivals": 4,...}

categories_impact object read-only

A map of the categories supported by the endpoint and its impact. For each category the value returned is a sum of the impact of the events in that category for the given day that match the parameters of the call to the endpoint. For example if on a given day under the conferences category there could be 3 events with a total impact of 3000 in this case the conferences value under categories_impact would be "conferences": 3000. The impact is of type number.

E.g. {"community": 2300, "concerts": 45190, "conferences": 700, "expos": 20, "festivals": 42,...}

count number read-only

Count of active events on a specific date. Note that an event that has an active date range which spans multiple days would be counted towards all of those dates.

E.g. 146

date string read-only

Aggregate Event Impact intersects the events' active dates with the search filters and then aggregates the results per day.

E.g. 2018-09-18

impact number read-only

impact is the total impact of all active events on a given day for all supported attendance-based categories. The following categories are supported: concerts, performing arts, sports, expos, conferences, community and festivals. The impact value for PHQ ranked events is based on looking at factors like the event attendance, venue capacity and a lot of other data PredictHQ captures about events, whereas Aviation Rank indicates how much an event will impact flight bookings by considering both domestic and international travel.

impact is designed to be used for demand correlation or as a feature in a machine learning model.

E.g. 147873

rank_levels object read-only or aviation_rank_levels object read-only

A map of count of events per rank level returned for a given day. This includes the count of rank levels from 1 to 5. For each rank level the number returned is the count of events with this rank level for the given day.

E.g. {"1": 85, "2": 36, "3": 21, "4": 0, "5": 4}

rank_levels_impact object read-only or aviation_rank_levels object read-only

A map of the total impact per rank level returned for a given day. This includes the impact for rank levels from 1 to 5. For each rank level the impact figure is the sum of the impact of all events in that rank level. This includes all events that match the search parameters passed to the endpoint.

E.g. {"1": 1480, "2": 4571, "3": 21822, "4": 0, "5": 120000}