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.
GET https://api.predicthq.com/v1/events/
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:
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.
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:
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:
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.
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:
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
|
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:
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.
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 |
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)
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
|
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. ​
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.
|
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
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:
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:
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:
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.
Field Components:
These components correspond to event fields that can be included in relevance. They are not included in relevance by default.
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:
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.
Can influence relevance.
E.g. ?start_around.origin=2018-12-19 |
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. [email protected],174.768368 or [email protected],174.768368 |
Below is a CSV of all supported airport codes and their respective
place_id.airport-codes.csv
384KB
Text
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:
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:
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:
E.g. [ { "entity_id": "328DxFUbRKvaiJJGyT2gReF", "type": "venue", "name": "Spark Arena", "formatted_address": "Mahuhu Crescent\nAuckland 1010\nNew Zealand" } ] |