Search Events

Search for events happening in a location and date range. Use our extensive filters to narrow down your results.

Results are limited by your subscription

Please note that you will not receive an error when requesting a date range or location that is outside of your subscription settings.

This is sometimes confused with missing data. If you're not seeing the results you expect to see then please ensure your subscription covers the location or time period you're searching for.

Your subscription settings can be viewed in Control Center.

Request

HTTP Request

GET https://api.predicthq.com/v1/events/

Query parameters

Parameter Description

Parameter	Description
`active.*` date range	The date from and/or to the events intersect with. Supports `gt`, `gte`, `lt`, `lte` and `tz` suffixes. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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: `academic` `school-holidays` `public-holidays` `observances` `politics` `conferences` `expos` `concerts` `festivals` `performing-arts` `sports` `community` `daylight-savings` `airport-delays` `severe-weather` `disasters` `terror` `health-warnings` E.g. `?category=school-holidays,public-holidays` Take a look at the Event Categories page for an overview of the different categories.
`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. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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`
`first_seen` date range	Find events by the time they were seen for the first time. Supported suffixes are: `gt`: greater than. `gte`: greater than or equal to. `lt`: less than. `lte`: less than or equal to. `tz`: time zone of the first_seen times used; a TZ Database name.Default is `UTC`. The format of first_seen times for this parameter is `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` E.g. `?first_seen.gte=2020-11-30`
`id` string	A comma-separated list of event identifiers. E.g. `?id=z13B3870YOgv`
`label` string	A comma-separated list of labels. Please note that all event labels are lowercase and that the search is case sensitive. E.g. `?label=holiday,observance` Supports `op` suffix to indicate whether to match labels using a logical `AND`. E.g. `?label=holiday,observance&label.op=all` available values academic academic-session agriculture air-quality airport american-football animal architecture arson ashfall assassination attack attraction australian-football auto-racing automotive autumn-holiday avalanche badminton bars-closed bars-open baseball basketball bicycle biological-hazard blizzard bombing boxing business campus career chemical chemical-accident christmas-holiday civil climate-change closed-doors clothing club coastal-event cold-wave comedy comic community concert conference construction corporate course craft cricket cyclone daylight-savings debates delay design digital disaster disaster-warning drought dust earthquake easter-holiday education election entertainment entertainment-closed entertainment-open environment environment-pollution epidemic epidemic-hazard esports estimated exam execution explosion expo extreme-weather f1 family fashion festival fighting fire flood fog food football fundraiser furniture gaming golf graduation gymnastics hail hazardous-surf hazmat health health-warning heat-wave hijacking hockey holiday holiday-christian holiday-hebrew holiday-hindu holiday-local holiday-local-common holiday-muslim holiday-national holiday-observed holiday-orthodox holiday-religious horse-racing horticulture hostage-crisis household hurricane hybrid-session ice-hockey in-person-session industrial indycar instrument ironman jewelry landslide local-market lockdown lpga marathon marine mass-shooting medical mineral minor-league mlb mls mma monster-truck motocross motogp movie music nascar natural nba nba-gleague ncaa nfl nhl nuclear nursing observance observance-local observance-season observance-united-nations observance-worldwide office olympic online-session outdoor packaging paper parade parliament performing-arts personal-care-closed personal-care-open pet pga plastic politics president print product rain rallies real-estate recreation-closed recreation-open referendum religion research-development restaurant-closed restaurant-open retail-closed retail-open rodeo rugby running sales sand school science seminar shooting skating snow soccer social space sport spring-holiday stabbing storm storm-surge summer-holiday suspected-attack suspected-bombing table-tennis technology tennis terror thanksgiving-holiday thunderstorm tool tornado tourism training transportation travel triathlon tropical-storm tsunami typhoon vehicle-accident volcano volleyball weather weather-warning wedding wildfire wind winter-holiday wnba worship-closed worship-open wrestling wwe youth-sport You can also use the count endpoint to fetch a list of available labels.
`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`
`location_confidence_score.*`number range	Supports `gt`, `gte`, `lt` and `lte` suffixes. Please note that use of a suffix is required. A unique attribute to Predicted Events that were generated from analyzing sets of recurring events. The score ranges from 1 to 5, representing the event’s propensity to change location with each recurrence. Higher scores indicate a higher consistency in location, while lower scores indicate the event’s location is more likely to shift once additional details become available. E.g. `?location_confidence_score.gte=3&location_confidence_score.lte=5`
`offset` number	The number of results to skip. The default is `0`. E.g. `?offset=20`
`parent.*`	Whether or not to include parent events / exclude child events. Note that Child events are those events that have a link to a parent event. Parent events are all the other events, whether they have children or not. See the documentation on umbrella events for more information on parent and child events. Currently supports the `include` suffix. `include`: Whether or not to include parent events in the response (required, valid options are `true`, `false` or `only`) `true`: include parent events (default behaviour) `false`: exclude parent events - this will return child events only `only`: only fetch parent events (exclude child events) Default value: `true`. Please note that use of a suffix is required. E.g. `?parent.include=false`
`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`
`phq_label.*` string	PHQ Labels leverage newer generation LLMs and classifier models. Currently available for `conferences`, `expos`, `festivals`, `community` and `performing-arts`. Legacy labels are available in a separate field to preserve backwards compatibility. A comma-separated list of PHQ Labels. Please note that all PHQ Labels are lowercase and that the search is case sensitive. Supports `exclude` suffix to get events without certain PHQ Labels and can be used without suffix for getting events with certain phq labels. E.g. `?phq_label.exclude=lifestyle&phq_label=agriculture-forestry-and-fisheries,food-and-beverage` As with legacy labels, PHQ Labels support the `op` suffix to indicate whether to match or exclude PHQ Labels using a logical `AND`. E.g. `?phq_label.exclude=lifestyle&phq_label=agriculture-forestry-and-fisheries,food-and-beverage&phq_label.op=all&phq_label.exclude.op=all` available values agriculture-forestry-and-fisheries alcohol art-and-cultural automotive beauty-and-fashion celebration charity circus comedy-club community-event concert construction-and-infrastructure consumer-goods cultural cultural-performance design-and-furnishing digital dinner-theatre education education-and-careers educational family-activities family-fun family-theatre festivals-and-outdoor-activities financial-services food-and-beverage general-theatre hospitality-and-travel legal-and-property-services lifestyle literature-film-and-theater logistics-and-transportation management-and-consulting manufacturing-and-petroleum-products market medical mining-drilling-and-metalwork movie music music-and-dance nature-and-outdoor-activities nightlife parade religion religion-and-spirituality science-and-technology sport sports-and-gaming textile visual-art wellness
`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. A CSV file of all supported airport codes and their respective place ids is available to download. 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`
`placekey` string	A comma-separated list of Placekeys (See placekey.io). Returns events that have a Placekey value matching this filter. There are 2 parts to a Placekey: `what@where` `What:`Contains 2 part in the form `{address}-{POI}`. The first part represents an address. The second part represents a Point Of Interest (E.g. named venue). This will be missing on locations that only have addresses `Where:` An H3 hexagon index(resolution 10) of the event. This filter supports entering a full Placekey to match events having that specific Placekey or a partial Placekey (such as just the `@where` part) to perform a partial match on Placekey. You can use the following Placekey format in this filter: `{address}-{poi}@{where}` - only returns events with a full matching placekey (an exact match) `{address}@{where}` - matches events where the the address and where part match (even if poi is different) `@{where}` - matches events for which the @Where part matches, ignores the {address}-{poi} parts. You can perform a partial match on the @Where part to find nearby events. The minimum amount of characters that can be matched on is 5. See using Placekey for more details. Note that Placekey applies to our attended event categories. Some events do not contain a Placekey. E.g.`?placekey=225@63j-rqb-j7q,@627-s8j-z2k`
`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. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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	The date from and/or to the event predicted_end. Supports `gt`, `gte`, `lt`, `lte` and `tz` suffixes. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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`
`predicted_event_spend.*` number range	The Predicted Event Spend across all supported industries for an event in USD. Supports `gt`, `gte`, `lt` and `lte` suffixes. Please note that use of a suffix is required. Note: When using this filter events that do not have a `predicted_event_spend` will not be returned. E.g. `?predicted_event_spend.gte=80000&predicted_event_spend.lte=200000`
`predicted_event_spend_industry.*` number range	The Predicted Event Spend for a given industry in USD. Supported industries: `accommodation` `hospitality` `transportation` The format of this parameter name is: `predicted_event_spend_industry.<industry>.<suffix>` Supports `gt`, `gte`, `lt` and `lte` suffixes. Please note that use of a suffix is required. Note: When using this filter events that do not have a `predicted_event_spend` will not be returned. E.g. `predicted_event_spend_industry.accommodation.gte=80000&predicted_event_spend_industry.accommodation.lte=200000`
`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`
`saved_location.location_id` string	A comma-separated list of saved location identifiers. Up to a maximum of 20 identifiers. This filters the events returned to events within the locations specified. See the Saved Locations API for more details on getting location IDs for a location. E.g. `?saved_location.location_id=sFlb8HlsLa1j-S4UDEMEkQ`
`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` `first_seen` `predicted_end` `updated` `rank` `local_rank` `aviation_rank` `phq_attendance` `category` `duration` `country` `labels` `relevance` `predicted_event_spend` `predicted_event_spend_industry.accommodation` `predicted_event_spend_industry.hospitality` `predicted_event_spend_industry.transportation` 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. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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`
`start_date_confidence_score.*`number range	Supports `gt`, `gte`, `lt` and `lte` suffixes. Please note that use of a suffix is required. A unique attribute to Predicted Events that were generated from analyzing sets of recurring events. The score ranges from 1 to 5, representing the event’s consistency in being held around the same date with each recurrence. Higher scores indicate the event is held at mostly the same date each year, while lower scores indicate a greater variation in start date, meaning that details are more likely to change as new details become available. E.g. `?start_date_confidence_score.gte=3&start_date_confidence_score.lte=5`
`state` string	A comma-separated list of states for the events. Supports `active`, `deleted` and `predicted`. 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. The accepted format for this parameter is either `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` 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: meters `m`, kilometers `km`, feet `ft`, miles `mi`. When using the units of `km` and `mi` you can enter whole numbers or floats `e.g. 5mi, 1.5km or 1.2mi`. When using the units `ft` or `m` you need to enter whole numbers (you cannot enter a fraction of a meter or foot). Note that results may contain events that apply to a parent scope of the specified area. Note that it can be difficult working out a suitable radius around your location so to make it easier please use our Suggested Radius API. E.g. National school holidays that apply to the local radius. E.g. `?within=2.5mi@-36.844480,174.768368` or `?within=2750m@-36.844480,174.768368`

active.* date range

The date from and/or to the events intersect with. Supports gt, gte, lt, lte and tz suffixes. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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:

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

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

Take a look at the Event Categories page for an overview of the different categories.

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. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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

first_seen date range

Find events by the time they were seen for the first time.

Supported suffixes are:

gt: greater than.
gte: greater than or equal to.
lt: less than.
lte: less than or equal to.
tz: time zone of the first_seen times used;

a TZ Database name.Default is UTC.

The format of first_seen times for this parameter is YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

E.g. ?first_seen.gte=2020-11-30

id string

A comma-separated list of event identifiers.

E.g. ?id=z13B3870YOgv

label string

A comma-separated list of labels. Please note that all event labels are lowercase and that the search is case sensitive.

E.g. ?label=holiday,observance

Supports op suffix to indicate whether to match labels using a logical AND.

E.g. ?label=holiday,observance&label.op=all

available values

academic
academic-session
agriculture
air-quality
airport
american-football
animal
architecture
arson
ashfall
assassination
attack
attraction
australian-football
auto-racing
automotive
autumn-holiday
avalanche
badminton
bars-closed
bars-open
baseball
basketball
bicycle
biological-hazard
blizzard
bombing
boxing
business
campus
career
chemical
chemical-accident
christmas-holiday
civil
climate-change
closed-doors
clothing
club
coastal-event
cold-wave
comedy
comic
community
concert
conference
construction
corporate
course
craft
cricket
cyclone
daylight-savings
debates
delay
design
digital
disaster
disaster-warning
drought
dust
earthquake
easter-holiday
education
election
entertainment
entertainment-closed
entertainment-open
environment
environment-pollution
epidemic
epidemic-hazard
esports
estimated
exam
execution
explosion
expo
extreme-weather
f1
family
fashion
festival
fighting
fire
flood
fog
food
football
fundraiser
furniture
gaming
golf
graduation
gymnastics
hail
hazardous-surf
hazmat
health
health-warning
heat-wave
hijacking
hockey
holiday
holiday-christian
holiday-hebrew
holiday-hindu
holiday-local
holiday-local-common
holiday-muslim
holiday-national
holiday-observed
holiday-orthodox
holiday-religious
horse-racing
horticulture
hostage-crisis
household
hurricane
hybrid-session
ice-hockey
in-person-session
industrial
indycar
instrument
ironman
jewelry
landslide
local-market
lockdown
lpga
marathon
marine
mass-shooting
medical
mineral
minor-league
mlb
mls
mma
monster-truck
motocross
motogp
movie
music
nascar
natural
nba
nba-gleague
ncaa
nfl
nhl
nuclear
nursing
observance
observance-local
observance-season
observance-united-nations
observance-worldwide
office
olympic
online-session
outdoor
packaging
paper
parade
parliament
performing-arts
personal-care-closed
personal-care-open
pet
pga
plastic
politics
president
print
product
rain
rallies
real-estate
recreation-closed
recreation-open
referendum
religion
research-development
restaurant-closed
restaurant-open
retail-closed
retail-open
rodeo
rugby
running
sales
sand
school
science
seminar
shooting
skating
snow
soccer
social
space
sport
spring-holiday
stabbing
storm
storm-surge
summer-holiday
suspected-attack
suspected-bombing
table-tennis
technology
tennis
terror
thanksgiving-holiday
thunderstorm
tool
tornado
tourism
training
transportation
travel
triathlon
tropical-storm
tsunami
typhoon
vehicle-accident
volcano
volleyball
weather
weather-warning
wedding
wildfire
wind
winter-holiday
wnba
worship-closed
worship-open
wrestling
wwe
youth-sport

You can also use the count endpoint to fetch a list of available labels.

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

location_confidence_score.*number range

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

A unique attribute to Predicted Events that were generated from analyzing sets of recurring events. The score ranges from 1 to 5, representing the event’s propensity to change location with each recurrence. Higher scores indicate a higher consistency in location, while lower scores indicate the event’s location is more likely to shift once additional details become available.

E.g. ?location_confidence_score.gte=3&location_confidence_score.lte=5

offset number

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

E.g. ?offset=20

parent.*

Whether or not to include parent events / exclude child events. Note that Child events are those events that have a link to a parent event. Parent events are all the other events, whether they have children or not.

See the documentation on umbrella events for more information on parent and child events. Currently supports the include suffix. include: Whether or not to include parent events in the response (required, valid options are true, false or only)

true: include parent events (default behaviour)
false: exclude parent events - this will return child events only
only: only fetch parent events (exclude child events)

Default value: true. Please note that use of a suffix is required. E.g. ?parent.include=false

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

phq_label.* string

PHQ Labels leverage newer generation LLMs and classifier models. Currently available for conferences, expos, festivals, community and performing-arts. Legacy labels are available in a separate field to preserve backwards compatibility. A comma-separated list of PHQ Labels. Please note that all PHQ Labels are lowercase and that the search is case sensitive. Supports exclude suffix to get events without certain PHQ Labels and can be used without suffix for getting events with certain phq labels.

E.g. ?phq_label.exclude=lifestyle&phq_label=agriculture-forestry-and-fisheries,food-and-beverage

As with legacy labels, PHQ Labels support the op suffix to indicate whether to match or exclude PHQ Labels using a logical AND.

E.g. ?phq_label.exclude=lifestyle&phq_label=agriculture-forestry-and-fisheries,food-and-beverage&phq_label.op=all&phq_label.exclude.op=all

available values

agriculture-forestry-and-fisheries
alcohol
art-and-cultural
automotive
beauty-and-fashion
celebration
charity
circus
comedy-club
community-event
concert
construction-and-infrastructure
consumer-goods
cultural
cultural-performance
design-and-furnishing
digital
dinner-theatre
education
education-and-careers
educational
family-activities
family-fun
family-theatre
festivals-and-outdoor-activities
financial-services
food-and-beverage
general-theatre
hospitality-and-travel
legal-and-property-services
lifestyle
literature-film-and-theater
logistics-and-transportation
management-and-consulting
manufacturing-and-petroleum-products
market
medical
mining-drilling-and-metalwork
movie
music
music-and-dance
nature-and-outdoor-activities
nightlife
parade
religion
religion-and-spirituality
science-and-technology
sport
sports-and-gaming
textile
visual-art
wellness

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.

A CSV file of all supported airport codes and their respective place ids is available to download.

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

placekey string

A comma-separated list of Placekeys (See placekey.io). Returns events that have a Placekey value matching this filter.

There are 2 parts to a Placekey: what@where

What:Contains 2 part in the form {address}-{POI}.
- The first part represents an address.
- The second part represents a Point Of Interest (E.g. named venue). This will be missing on locations that only have addresses
Where: An H3 hexagon index(resolution 10) of the event.

This filter supports entering a full Placekey to match events having that specific Placekey or a partial Placekey (such as just the @where part) to perform a partial match on Placekey. You can use the following Placekey format in this filter:

{address}-{poi}@{where} - only returns events with a full matching placekey (an exact match)
{address}@{where} - matches events where the the address and where part match (even if poi is different)
@{where} - matches events for which the @Where part matches, ignores the {address}-{poi} parts. You can perform a partial match on the @Where part to find nearby events. The minimum amount of characters that can be matched on is 5. See using Placekey for more details.

Note that Placekey applies to our attended event categories. Some events do not contain a Placekey. E.g.?placekey=225@63j-rqb-j7q,@627-s8j-z2k

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. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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

The date from and/or to the event predicted_end. Supports gt, gte, lt, lte and tz suffixes. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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

predicted_event_spend.* number range

The Predicted Event Spend across all supported industries for an event in USD. Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

Note: When using this filter events that do not have a predicted_event_spend will not be returned.

E.g. ?predicted_event_spend.gte=80000&predicted_event_spend.lte=200000

predicted_event_spend_industry.* number range

The Predicted Event Spend for a given industry in USD. Supported industries:

accommodation
hospitality
transportation

The format of this parameter name is:

predicted_event_spend_industry.<industry>.<suffix>

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

Note: When using this filter events that do not have a predicted_event_spend will not be returned.

E.g. predicted_event_spend_industry.accommodation.gte=80000&predicted_event_spend_industry.accommodation.lte=200000

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

saved_location.location_id string

A comma-separated list of saved location identifiers. Up to a maximum of 20 identifiers. This filters the events returned to events within the locations specified. See the Saved Locations API for more details on getting location IDs for a location.

E.g. ?saved_location.location_id=sFlb8HlsLa1j-S4UDEMEkQ

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
first_seen
predicted_end
updated
rank
local_rank
aviation_rank
phq_attendance
category
duration
country
labels
relevance
predicted_event_spend
predicted_event_spend_industry.accommodation
predicted_event_spend_industry.hospitality
predicted_event_spend_industry.transportation

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. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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

start_date_confidence_score.*number range

Supports gt, gte, lt and lte suffixes.

Please note that use of a suffix is required.

A unique attribute to Predicted Events that were generated from analyzing sets of recurring events. The score ranges from 1 to 5, representing the event’s consistency in being held around the same date with each recurrence. Higher scores indicate the event is held at mostly the same date each year, while lower scores indicate a greater variation in start date, meaning that details are more likely to change as new details become available.

E.g. ?start_date_confidence_score.gte=3&start_date_confidence_score.lte=5

state string

A comma-separated list of states for the events. Supports active, deleted and predicted. 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. The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss 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: meters m, kilometers km, feet ft, miles mi. When using the units of km and mi you can enter whole numbers or floats e.g. 5mi, 1.5km or 1.2mi. When using the units ft or m you need to enter whole numbers (you cannot enter a fraction of a meter or foot). Note that results may contain events that apply to a parent scope of the specified area. Note that it can be difficult working out a suitable radius around your location so to make it easier please use our Suggested Radius API. E.g. National school holidays that apply to the local radius. E.g. ?within=2.5mi@-36.844480,174.768368 or ?within=2750m@-36.844480,174.768368

Mapping File

Below is a CSV of all supported airport codes and their respective place_id.

384KB

airport-codes.csv

Response

Response Fields

Field Description

Field	Description
`aviation_rank` number, null	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	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	The category of the event Possible values: `academic` `school-holidays` `public-holidays` `observances` `politics` `conferences` `expos` `concerts` `festivals` `performing-arts` `sports` `community` `daylight-savings` `airport-delays` `severe-weather` `disasters` `terror` `health-warnings` E.g. `concerts`
`country` string	The country code in ISO 3166-1 alpha-2 format. Note that the `country` value will usually be present but in some cases where the event location is not within a country (e.g. an earthquake in the middle of the ocean) it can be empty. E.g. `NZ`
`deleted_reason` string	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	A description of the event. E.g. `See Katy Perry in concert [...]`
`duplicate_of_id` string	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	The duration of the event in seconds. E.g. `3600`
`end` string	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	An array of entities linked to the event. Possible types: `event-group` `venue` E.g. `[ { "entity_id": "328DxFUbRKvaiJJGyT2gReF", "type": "venue", "name": "Spark Arena", "formatted_address": "Mahuhu Crescent\nAuckland 1010\nNew Zealand" } ]`
`first_seen` string, null	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	The unique identifier of the event. E.g. `z13B3870YOgv`
`impact_patterns` array	Also known as “Demand impact patterns”. This field shows the impact for leading days (days before the event), lagging days (days after an event), and the days the event occurs. See Impact Patternsfor more details. `impact_patterns` is an array of impact pattern objects. The same event can have different impact patterns for different industry verticals. It contains the following fields: `vertical` - The industry vertical the impact pattern applies to. `impact_type` - Indicates the type of impact shown in the impact pattern. Currently, the supported types are phq_rank and phq_attendance. If the impact_type is phq_rank then the impact values shown per day reflect phq_rank values. If impact_type is phq_attendance then the impact values per day reflect phq_attendance which is the estimated amount of people attending the event per day. `impacts` is an array of objects with one entry for each day that contains the following values: `date_local` - the date in the local timezone of the event. `value` - the value of the `impact_type` for that given day. For example, if the `impact_type` was `phq_rank` the value would be the PHQ Rank value on the given day. Otherwise, it will reflect `phq_attendance` `position` - can be `leading`, `event_day` or `lagging`. `leading` are the days before the event occurs, `event_day` are the days the event occurs and `lagging` are the days after the event has occurred. The example below is based on an `impact_type` of `phq_rank` for severe weather events. `[ { "date_local": "2022-01-08", "value": 10, "position": "leading" }, { "date_local": "2022-01-09", "value": 21, "position": "event_day" }, ... ]`
`labels` array	The labels associated with the event. E.g. `["holiday", "holiday-national"]` possible labels academic academic-session agriculture air-quality airport american-football animal architecture arson ashfall assassination attack attraction australian-football auto-racing automotive autumn-holiday avalanche badminton bars-closed bars-open baseball basketball bicycle biological-hazard blizzard bombing boxing business campus career chemical chemical-accident christmas-holiday civil climate-change closed-doors clothing club coastal-event cold-wave comedy comic community concert conference construction corporate course craft cricket cyclone daylight-savings debates delay design digital disaster disaster-warning drought dust earthquake easter-holiday education election entertainment entertainment-closed entertainment-open environment environment-pollution epidemic epidemic-hazard esports estimated exam execution explosion expo extreme-weather f1 family fashion festival fighting fire flood fog food football fundraiser furniture gaming golf graduation gymnastics hail hazardous-surf hazmat health health-warning heat-wave hijacking hockey holiday holiday-christian holiday-hebrew holiday-hindu holiday-local holiday-local-common holiday-muslim holiday-national holiday-observed holiday-orthodox holiday-religious horse-racing horticulture hostage-crisis household hurricane hybrid-session ice-hockey in-person-session industrial indycar instrument ironman jewelry landslide local-market lockdown lpga marathon marine mass-shooting medical mineral minor-league mlb mls mma monster-truck motocross motogp movie music nascar natural nba nba-gleague ncaa nfl nhl nuclear nursing observance observance-local observance-season observance-united-nations observance-worldwide office olympic online-session outdoor packaging paper parade parliament performing-arts personal-care-closed personal-care-open pet pga plastic politics president print product rain rallies real-estate recreation-closed recreation-open referendum religion research-development restaurant-closed restaurant-open retail-closed retail-open rodeo rugby running sales sand school science seminar shooting skating snow soccer social space sport spring-holiday stabbing storm storm-surge summer-holiday suspected-attack suspected-bombing table-tennis technology tennis terror thanksgiving-holiday thunderstorm tool tornado tourism training transportation travel triathlon tropical-storm tsunami typhoon vehicle-accident volcano volleyball weather weather-warning wedding wildfire wind winter-holiday wnba worship-closed worship-open wrestling wwe youth-sport You can also use the count endpoint to fetch a list of available labels.
`local_rank` number, null	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	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]`
`location_confidence_score` number	The Predicted Event location confidence score.
`geo` object	An object containing the geographic information about an event. This field will be used in future instead of the location field (the location field will remain in the current version of the API but could be removed in future versions). Currently, this field has only one subfield: geometry, which represents the geometry associated with the event in the GeoJSON format. Possible types: `Point` `Polygon` `MultiPolygon` E.g. `{ "geometry": { "type": "Point", "coordinates": [174.776792, -36.847319] } }`
`parent_event` object	Used to indicate if this event is part of a larger event. These types of events are called umbrella events in the system. For example, a large multi-day parent umbrella event may have individual child events for sessions on different days. For example the Formula 1 2019 United States Grand Prix has child events for the qualification, 3 practice events, a concert that occurs at the Grand Prix, and the actual race events (there are 12 child events). See umbrella events for details on this field and details on what umbrella events are. Note that this field in this release only shows if a child event has a parent id. It does not indicate if a parent event has child events. E.g. `{ "parent_event": { "parent_event_id": "w7dYyrFwTUQGYE6euv" } }`
`phq_attendance` number	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. phq_attendance reflects the entire attendance for multi-day events (the number of people attending across the full duration of the event) except for some categories like conferences where it is the daily attendance. See Handling multi-day and Umbrella events for more details. E.g. `2511`
`phq_labels` array	An array of objects which contains the PHQ Labels associated to an event as well as the weight that they contribute to the event. Weights from all labels should sum up to 1. PHQ Labels leverage newer generation LLMs and classifier models. Currently available for `conferences`, `expos`, `festivals`, `community` and `performing-arts` categories. Legacy labels are available in a separate field to preserve backwards compatibility. E.g. `[ { "label": "agriculture-forestry-and-fisheries", "weight": 0.376 }, { "label": "food-and-beverage", "weight": 0.263 }, { "label": "art-and-cultural", "weight": 0.186 }, { "label": "science-and-technology", "weight": 0.175 } ]` possible phq_labels.label agriculture-forestry-and-fisheries alcohol art-and-cultural automotive beauty-and-fashion celebration charity circus comedy-club community-event concert construction-and-infrastructure consumer-goods cultural cultural-performance design-and-furnishing digital dinner-theatre education education-and-careers educational family-activities family-fun family-theatre festivals-and-outdoor-activities financial-services food-and-beverage general-theatre hospitality-and-travel legal-and-property-services lifestyle literature-film-and-theater logistics-and-transportation management-and-consulting manufacturing-and-petroleum-products market medical mining-drilling-and-metalwork movie music music-and-dance nature-and-outdoor-activities nightlife parade religion religion-and-spirituality science-and-technology sport sports-and-gaming textile visual-art wellness
`place_hierarchies` array	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` Note that the `place_hierarchies` value can be an empty array in some cases. E.g. `[ [ "6295630", "6255148", "2635167", "6269131", "3333178", "2641170" ] ]`
`placekey` string	The Placekey (See placekey.io) reflects the location of an event in the format `what@where`. Placekey is part of the geo field for an event. Possible formats `{address}-{poi}@{where}` `{address)@{where}` `@where` E.g. `222-229@8t2-fgc-z2k` or `@7f7-mcy-ndv` Note that Placekey applies to our attended event categories. Some events do not contain a Placekey.
`postponed` string, null	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	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`
`predicted_event_spend` number	The total Predicted Event Spend across all supported industries for an event in USD. This figure represents the consumer spend impact on local businesses that the event is predicted to generate. E.g. `11806680`
`predicted_event_spend_industries` object	The Predicted Event Spend for each supported industry in USD. Possible industries: `accommodation` - The consumer spend predicted to be attributed to hotels and hosts. `hospitality` - The consumer spend predicted to be attributed to food and beverage. `transportation` - The consumer spend predicted to be attributed to ground-based transportation as a means of getting to and from the event. E.g. `{ "predicted_event_spend_industries": { "accommodation": 5016960, "hospitality": 4924000, "transportation": 1865720 } }`
`rank` number	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	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	The geographical scope the events apply to. Possible values: `locality` `localadmin` `county` `region` `country` E.g. `locality`
`start` string	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`
`start_date_confidence_score` number	The Predicted Event start date confidence score.
`state` string	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. `predicted`: events that have an unconfirmed start time i.e for which the exact time the event begins is not yet known.
`timezone` string, null	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	The title of the event. E.g. `Katy Perry`
`updated` string	The last modification date of the event in ISO 8601 format. All dates are in UTC. E.g. `2018-05-01T05:00:00Z`

aviation_rank number, null

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

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

The category of the event Possible values:

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

E.g. concerts

country string

The country code in ISO 3166-1 alpha-2 format. Note that the country value will usually be present but in some cases where the event location is not within a country (e.g. an earthquake in the middle of the ocean) it can be empty. E.g. NZ

deleted_reason string

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

A description of the event. E.g. See Katy Perry in concert [...]

duplicate_of_id string

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

The duration of the event in seconds. E.g. 3600

end string

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

An array of entities linked to the event. Possible types:

event-group
venue

E.g.

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

first_seen string, null

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

The unique identifier of the event. E.g. z13B3870YOgv

impact_patterns array

Also known as “Demand impact patterns”. This field shows the impact for leading days (days before the event), lagging days (days after an event), and the days the event occurs. See Impact Patternsfor more details. impact_patterns is an array of impact pattern objects. The same event can have different impact patterns for different industry verticals. It contains the following fields:

vertical - The industry vertical the impact pattern applies to.
impact_type - Indicates the type of impact shown in the impact pattern. Currently, the supported types are phq_rank and phq_attendance. If the impact_type is phq_rank then the impact values shown per day reflect phq_rank values. If impact_type is phq_attendance then the impact values per day reflect phq_attendance which is the estimated amount of people attending the event per day.

impacts is an array of objects with one entry for each day that contains the following values:

date_local - the date in the local timezone of the event.
value - the value of the impact_type for that given day. For example, if the impact_type was phq_rank the value would be the PHQ Rank value on the given day. Otherwise, it will reflect phq_attendance
position - can be leading, event_day or lagging. leading are the days before the event occurs, event_day are the days the event occurs and lagging are the days after the event has occurred.

The example below is based on an impact_type of phq_rank for severe weather events.

[
  {
    "date_local": "2022-01-08",
    "value": 10,
    "position": "leading"
  },
  {
    "date_local": "2022-01-09",
    "value": 21,
    "position": "event_day"
  },
  ...
]

labels array

The labels associated with the event. E.g. ["holiday", "holiday-national"]

possible labels

academic
academic-session
agriculture
air-quality
airport
american-football
animal
architecture
arson
ashfall
assassination
attack
attraction
australian-football
auto-racing
automotive
autumn-holiday
avalanche
badminton
bars-closed
bars-open
baseball
basketball
bicycle
biological-hazard
blizzard
bombing
boxing
business
campus
career
chemical
chemical-accident
christmas-holiday
civil
climate-change
closed-doors
clothing
club
coastal-event
cold-wave
comedy
comic
community
concert
conference
construction
corporate
course
craft
cricket
cyclone
daylight-savings
debates
delay
design
digital
disaster
disaster-warning
drought
dust
earthquake
easter-holiday
education
election
entertainment
entertainment-closed
entertainment-open
environment
environment-pollution
epidemic
epidemic-hazard
esports
estimated
exam
execution
explosion
expo
extreme-weather
f1
family
fashion
festival
fighting
fire
flood
fog
food
football
fundraiser
furniture
gaming
golf
graduation
gymnastics
hail
hazardous-surf
hazmat
health
health-warning
heat-wave
hijacking
hockey
holiday
holiday-christian
holiday-hebrew
holiday-hindu
holiday-local
holiday-local-common
holiday-muslim
holiday-national
holiday-observed
holiday-orthodox
holiday-religious
horse-racing
horticulture
hostage-crisis
household
hurricane
hybrid-session
ice-hockey
in-person-session
industrial
indycar
instrument
ironman
jewelry
landslide
local-market
lockdown
lpga
marathon
marine
mass-shooting
medical
mineral
minor-league
mlb
mls
mma
monster-truck
motocross
motogp
movie
music
nascar
natural
nba
nba-gleague
ncaa
nfl
nhl
nuclear
nursing
observance
observance-local
observance-season
observance-united-nations
observance-worldwide
office
olympic
online-session
outdoor
packaging
paper
parade
parliament
performing-arts
personal-care-closed
personal-care-open
pet
pga
plastic
politics
president
print
product
rain
rallies
real-estate
recreation-closed
recreation-open
referendum
religion
research-development
restaurant-closed
restaurant-open
retail-closed
retail-open
rodeo
rugby
running
sales
sand
school
science
seminar
shooting
skating
snow
soccer
social
space
sport
spring-holiday
stabbing
storm
storm-surge
summer-holiday
suspected-attack
suspected-bombing
table-tennis
technology
tennis
terror
thanksgiving-holiday
thunderstorm
tool
tornado
tourism
training
transportation
travel
triathlon
tropical-storm
tsunami
typhoon
vehicle-accident
volcano
volleyball
weather
weather-warning
wedding
wildfire
wind
winter-holiday
wnba
worship-closed
worship-open
wrestling
wwe
youth-sport

You can also use the count endpoint to fetch a list of available labels.

local_rank number, null

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

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]

location_confidence_score number

The Predicted Event location confidence score.

geo object

An object containing the geographic information about an event. This field will be used in future instead of the location field (the location field will remain in the current version of the API but could be removed in future versions). Currently, this field has only one subfield: geometry, which represents the geometry associated with the event in the GeoJSON format. Possible types:

Point
Polygon
MultiPolygon

E.g.

{
  "geometry": {
    "type": "Point",
    "coordinates": [174.776792, -36.847319]
  }
}

parent_event object

Used to indicate if this event is part of a larger event. These types of events are called umbrella events in the system. For example, a large multi-day parent umbrella event may have individual child events for sessions on different days. For example the Formula 1 2019 United States Grand Prix has child events for the qualification, 3 practice events, a concert that occurs at the Grand Prix, and the actual race events (there are 12 child events). See umbrella events for details on this field and details on what umbrella events are. Note that this field in this release only shows if a child event has a parent id. It does not indicate if a parent event has child events.

E.g.

{
  "parent_event": {
    "parent_event_id": "w7dYyrFwTUQGYE6euv"
  }
}

phq_attendance number

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. phq_attendance reflects the entire attendance for multi-day events (the number of people attending across the full duration of the event) except for some categories like conferences where it is the daily attendance. See Handling multi-day and Umbrella events for more details. E.g. 2511

phq_labels array

An array of objects which contains the PHQ Labels associated to an event as well as the weight that they contribute to the event. Weights from all labels should sum up to 1. PHQ Labels leverage newer generation LLMs and classifier models. Currently available for conferences, expos, festivals, community and performing-arts categories. Legacy labels are available in a separate field to preserve backwards compatibility.

E.g.

[
  {
    "label": "agriculture-forestry-and-fisheries",
    "weight": 0.376
  },
  {
    "label": "food-and-beverage",
    "weight": 0.263
  },
  {
    "label": "art-and-cultural",
    "weight": 0.186
  },
  {
    "label": "science-and-technology",
    "weight": 0.175
  }
]

possible phq_labels.label

agriculture-forestry-and-fisheries
alcohol
art-and-cultural
automotive
beauty-and-fashion
celebration
charity
circus
comedy-club
community-event
concert
construction-and-infrastructure
consumer-goods
cultural
cultural-performance
design-and-furnishing
digital
dinner-theatre
education
education-and-careers
educational
family-activities
family-fun
family-theatre
festivals-and-outdoor-activities
financial-services
food-and-beverage
general-theatre
hospitality-and-travel
legal-and-property-services
lifestyle
literature-film-and-theater
logistics-and-transportation
management-and-consulting
manufacturing-and-petroleum-products
market
medical
mining-drilling-and-metalwork
movie
music
music-and-dance
nature-and-outdoor-activities
nightlife
parade
religion
religion-and-spirituality
science-and-technology
sport
sports-and-gaming
textile
visual-art
wellness

place_hierarchies array

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 Note that the place_hierarchies value can be an empty array in some cases.

E.g.

[
  [
    "6295630",
    "6255148",
    "2635167",
    "6269131",
    "3333178",
    "2641170"
  ]
]

placekey string

The Placekey (See placekey.io) reflects the location of an event in the format what@where. Placekey is part of the geo field for an event. Possible formats

{address}-{poi}@{where}
{address)@{where}
@where

E.g. 222-229@8t2-fgc-z2k or @7f7-mcy-ndv Note that Placekey applies to our attended event categories. Some events do not contain a Placekey.

postponed string, null

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

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

predicted_event_spend number

The total Predicted Event Spend across all supported industries for an event in USD. This figure represents the consumer spend impact on local businesses that the event is predicted to generate. E.g. 11806680

predicted_event_spend_industries object

The Predicted Event Spend for each supported industry in USD.

Possible industries:

accommodation - The consumer spend predicted to be attributed to hotels and hosts.
hospitality - The consumer spend predicted to be attributed to food and beverage.
transportation - The consumer spend predicted to be attributed to ground-based transportation as a means of getting to and from the event.

E.g.

{
  "predicted_event_spend_industries": {
    "accommodation": 5016960,
    "hospitality": 4924000,
    "transportation": 1865720
  }
}

rank number

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

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

The geographical scope the events apply to. Possible values:

locality
localadmin
county
region
country

E.g. locality

start string

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

start_date_confidence_score number

The Predicted Event start date confidence score.

state string

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.
predicted: events that have an unconfirmed start time i.e for which the exact time the event begins is not yet known.

timezone string, null

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

The title of the event. E.g. Katy Perry

updated string

The last modification date of the event in ISO 8601 format. All dates are in UTC. E.g. 2018-05-01T05:00:00Z

JSON Schema

1KB

events-response-schema.json

10KB

event-schema.json

Example response

Below is an example of a single result.

{
  "count": 1,
  "overflow": false,
  "next": null,
  "previous": null,
  "results": [
    {
      "relevance": 0.0,
      "id": "5uRg7CqGu7DTtu4Rfk",
      "parent_event": {
        "parent_event_id": "w7dYyrFwTUQGYE6euv"
      },
      "title": "Formula 1 2019 - United States Grand Prix 2019 - Race",
      "description": "The 2019 United States Grand Prix (officially known as the Formula 1 Emirates United States Grand Prix 2019) was a Formula One motor race held on 3 November 2019 at the Circuit of the Americas in Austin, Texas, United States. The race was the 19th round of the 2019 Formula One World Championship (1 - 3 Nov) and marked the 49th running of the United States Grand Prix.",
      "category": "sports",
      "labels": [
        "auto-racing",
        "f1",
        "sport"
      ],
      "rank": 92,
      "local_rank": 100,
      "phq_attendance": 120000,
      "entities": [
        {
          "entity_id": "dh6tCwHCRjZUNmzaviVw5g",
          "name": "Carlos Sainz Jr",
          "type": "person"
        },
        {
          "entity_id": "fqGj7EdaKsDPGFUgsYhYWq",
          "name": "Kevin Magnussen",
          "type": "person"
        },
        {
          "entity_id": "e5rtDESKg4fLpHzmTcdAxy",
          "name": "Alexander Albon",
          "type": "person"
        },
        {
          "entity_id": "DtXbSrLe9Mb9BQfjzt8q3Q",
          "name": "Sergio Perez",
          "type": "person"
        },
        {
          "entity_id": "32wsZ6AhQTmehuPV9KwqgCY",
          "name": "Lewis Hamilton",
          "type": "person"
        },
        {
          "entity_id": "hdqmJpv6pbCNT5RMLjiQr8",
          "name": "Lando Norris",
          "type": "person"
        },
        {
          "entity_id": "dXA6AvcgEg7W5SJdjcgAAG",
          "name": "Lance Stroll",
          "type": "person"
        },
        {
          "entity_id": "sn3aet9XXYWPu2RmNMVsAG",
          "name": "Daniil Kvyat",
          "type": "person"
        },
        {
          "entity_id": "hKiTqaaffAzV4wGntE6LH8",
          "name": "Robert Kubica",
          "type": "person"
        },
        {
          "entity_id": "eG36WTqRtMwvjHM7SLHwiG",
          "name": "Antonio Giovinazzi",
          "type": "person"
        },
        {
          "entity_id": "JpFCtMes9vVbXxKduZ9jTd",
          "name": "Nicholas Latifi",
          "type": "person"
        },
        {
          "entity_id": "fS2HcqsbnzuCtXgUqch6Py",
          "name": "Max Verstappen",
          "type": "person"
        },
        {
          "entity_id": "dMezEeCcEa9T7RscX4aBmg",
          "name": "Valtteri Bottas",
          "type": "person"
        },
        {
          "entity_id": "DhfPt6zSSUjUrWWfCpukkY",
          "name": "Sebastian Vettel",
          "type": "person"
        },
        {
          "entity_id": "fdX7zyHMKYjAjJhSKhAvaG",
          "name": "Charles Leclerc",
          "type": "person"
        },
        {
          "entity_id": "XS7dVfwZBETRejm7en3Adg",
          "name": "Pierre Gasly",
          "type": "person"
        },
        {
          "entity_id": "33RfRSKSNRfuAzAYWEV8mR8",
          "name": "George Russell",
          "type": "person"
        },
        {
          "entity_id": "e5rv77Gws6cKNCmJra5VFy",
          "name": "Daniel Ricciardo",
          "type": "person"
        },
        {
          "entity_id": "7NT7S5KqiwqdKZiwsydzz8",
          "name": "Nico Hulkenberg",
          "type": "person"
        },
        {
          "entity_id": "MasUgUJtWz3kQFVgCG6rJU",
          "name": "Circuit of the Americas",
          "type": "venue",
          "formatted_address": "9201 Circuit of the Americas Boulevard\nAustin, TX 78617\nUnited States of America"
        }
      ],
      "duration": 7200,
      "start": "2019-11-03T19:10:00Z",
      "end": "2019-11-03T21:10:00Z",
      "updated": "2023-06-02T16:21:48Z",
      "first_seen": "2019-07-04T22:14:31Z",
      "timezone": "America/Chicago",
      "location": [
        -97.63585109999997,
        30.1345808
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -97.63585109999997,
            30.1345808
          ],
          "type": "Point"
        },
        "placekey": "zzw-222@8t2-fgg-gtv"
      },
      "scope": "locality",
      "country": "US",
      "place_hierarchies": [
        [
          "6295630",
          "6255149",
          "6252001",
          "4736286",
          "4737316",
          "4689116"
        ],
        [
          "6295630",
          "6255149",
          "6252001",
          "4736286",
          "4737316",
          "4671654"
        ]
      ],
      "state": "active",
      "private": false,
      "predicted_event_spend": 11806680,
      "predicted_event_spend_industries": {
        "accommodation": 5016960,
        "hospitality": 4924000,
        "transportation": 1865720
      }
    }
  ]
}

Examples

curl -X GET https://api.predicthq.com/v1/events/?id=5uRg7CqGu7DTtu4Rfk \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "id": "5uRg7CqGu7DTtu4Rfk"
    }
)

print(response.json())

Guides

Below are some guides relevant to this API:

PreviousEvents NextGet Event Counts

Last updated 1 month ago