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
Query parameters
Parameter | Description |
---|---|
| The date from and/or to the events intersect with. Supports |
| Supports Please note that use of a suffix is required.
Note when filtering on E.g. |
| A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ Aviation Rank levels. Possible values:
Note when filtering on
E.g. |
| Whether or not to exclude potentially brand-unsafe events. Potentially brand-unsafe events are included by default.
Currently only supports the
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. |
| The date from and/or to the event was set to cancelled in the system. Supports
E.g. |
| A comma-separated list of categories. Possible values:
E.g. Take a look at the Event Categories page for an overview of the different categories. |
| A comma-separated list of country codes.
E.g. |
| A comma-separated list of deleted reasons for the events. Possible values:
E.g. |
| The date from and/or to the event ends. Supports
E.g. |
| Fuzzy date search around event end. Supports
Can influence
E.g. |
| A comma-separated list of entity identifiers.
E.g. |
| Find events by the time they were seen for the first time. Supported suffixes are:
a TZ Database name.Default is
The format of first_seen times for this parameter is E.g. |
| A comma-separated list of event identifiers.
E.g. |
| A comma-separated list of labels. Please note that all event labels are lowercase and that the search is case sensitive. E.g. Supports
E.g. You can also use the count endpoint to fetch a list of available labels. |
| The maximum number of results to return. The default limit is
E.g. |
| Supports Please note that use of a suffix is required.
Note when filtering on
E.g. |
| A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ local rank levels. Possible values:
Note when filtering on E.g. |
| Fuzzy location search around event location.
Please note this affects the
Supports
E.g. |
| Supports 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. |
| The number of results to skip. The default is
E.g. |
| 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
Default value: |
| Supports Please note that use of a suffix is required.
E.g. |
| PHQ Labels leverage newer generation LLMs and classifier models. Currently available for
E.g. As with legacy labels, PHQ Labels support the E.g. |
| 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 A CSV file of all supported airport codes and their respective place ids is available to download.
When E.g.
|
| 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:
This filter supports entering a full Placekey to match events having that specific Placekey or a partial Placekey (such as just the
Note that Placekey applies to our attended event categories. Some events do not contain a Placekey.
E.g. |
| The date from and/or to the event was set to postponed in the system. Supports
Note when filtering on
E.g. |
| The date from and/or to the event predicted_end. Supports
Note when filtering on E.g. |
| The Predicted Event Spend across all supported industries for an event in USD.
Supports Please note that use of a suffix is required. Note: When using this filter events that do not have a E.g. |
| The Predicted Event Spend for a given industry in USD. Supported industries:
The format of this parameter name is: Supports Please note that use of a suffix is required. Note: When using this filter events that do not have a E.g. |
| A full-text search query.
Can influence
E.g. |
| Supports Please note that use of a suffix is required.
E.g. |
| A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ rank levels. Possible values:
E.g. |
| A comma-separated list of components to include when calculating the
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,
Field Components:
These components correspond to event fields that can be included in relevance. They are not included in
E.g. |
| 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. |
| A comma-separated list of fields to sort results by. The default is Possible values:
Note when sorting on E.g. |
| The date from and/or to the event starts. Supports
E.g. |
| Fuzzy date search around event start. Supports
Can influence
E.g. |
| Supports 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. |
| A comma-separated list of states for the events. Supports |
| The date from and/or to the event was last modified. Supports |
| A geo center and radius in the form |
Mapping File
Below is a CSV of all supported airport codes and their respective place_id
.
Response
Response Fields
Field | Description |
---|---|
| 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 |
| 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 |
| The category of the event Possible values:
E.g. |
| The country code in ISO 3166-1 alpha-2 format.
Note that the |
| The reason why the event was deleted.
Note that this field is only present for events with state
E.g. |
| A description of the event.
E.g. |
| The |
| The duration of the event in seconds.
E.g. |
| 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 |
| An array of entities linked to the event. Possible types:
E.g. |
| 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. |
| The unique identifier of the event.
E.g. |
| 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.
The example below is based on an |
| The labels associated with the event.
E.g. You can also use the count endpoint to fetch a list of available labels. |
| 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 |
| A 2-tuple representing the geo location of the event. Note that the longitude/latitude coordinates use the GeoJSON order [lon, lat].
E.g. |
| The Predicted Event location confidence score. |
| 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:
E.g. |
| 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. |
| 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. |
| 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 E.g. |
| 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: E.g. |
| The Placekey (See placekey.io) reflects the location of an event in the format
E.g. |
| 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 |
| 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 |
| 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. |
| The Predicted Event Spend for each supported industry in USD. Possible industries:
E.g. |
| 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. |
| Relative relevance of the event to the event search. See the relevance parameter for information on how relevance is calculated.
E.g. |
| The geographical scope the events apply to. Possible values:
E.g. |
| 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 |
| The Predicted Event start date confidence score. |
| The publication state of the event. Possible values:
|
| 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 |
| The title of the event.
E.g. |
| The last modification date of the event in ISO 8601 format. All dates are in UTC.
E.g. |
JSON Schema
Examples
Guides
Below are some guides relevant to this API:
Other Event API Guides
Last updated