Search Events
The largest and most accurate source of global data.
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
active.*
date range
The date range during which events occur.
E.g. ?active.gt=2024-01-01&active.lte=2024-01-05&active.tz=America/New_York
beam.*
beam filters
An optional beam analysis filter which if provided will calculate the location, rank and categories from the Beam analysis and optionally the Beam analysis group.
Supports analysis_id and group_id suffixes.
analysis_id(required)group_id(optional)
If the group_id suffix is provided the categories will be calculated from the feature importance of the analysis group otherwise the categories will be calculated from the feature importance of the individual analysis.
Please note that use of a suffix is required.
E.g. ?beam.analysis_id=0SXAmHsoZo0
&beam.group_id=QxE9BcLq7ZY
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 aretrueorfalse)
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 range during which events were marked as cancelled in the system.
E.g. ?cancelled.gte=2020-03-01&cancelled.lte=2020-03-15
Note when filtering on cancelled, events that are not cancelled will not be returned.
category
string
A comma-separated list of categories.
Possible values:
academicschool-holidayspublic-holidaysobservancespoliticsconferencesexposconcertsfestivalsperforming-artssportscommunitydaylight-savingsairport-delayssevere-weatherdisastersterrorhealth-warnings
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:
cancelledinvalidduplicatepostponed
E.g. ?deleted_reason=cancelled,duplicate
end.*
date range
The date range during which events end.
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 to0d)scale: Distance from origin +/- offset at which the score will equal the decay value (optional, defaults to3d)decay: Score value at thescaledistance (optional, defaults to0.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
The date range during which events are first seen in the system.
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. ?first_seen.gte=2020-11-30
id
string
A comma-separated list of event identifiers.
E.g. ?id=z13B3870YOgv
impact.*
date range
The impact range of the events (which could be larger than the actual event range).
This parameter works similarly to the active.* parameter, but it uses industry-specific impact range of an event where applicable.
For this parameter to work an additional parameter must be specified: impact.industry, which must be one of the following:
accomodationcpgtourismmarketingrestaurantsretailtransportation
E.g. ?impact.gt=2024-01-01&impact.lte=2024-01-05&impact.tz=America/New_York&impact.industry=accommodation
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 per page. 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.
Supports origin, offset, scale, decay suffixes.
origin: The location in the form{latitude},{longitude}(required)offset: The distance before decay is applied (optional, defaults to0km)(Distance unit can be one ofm,km,ft,mi)scale: Distance from origin + offset at which the score will equal decay value (optional, defaults to2km) (Distance unit can be one ofm,km,ft,mi)decay: Score value atscalevalue (optional, defaults to0.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.
true: include parent events (default behaviour)false: exclude parent events - this will return child events onlyonly: 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
place.*
place
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=5128638all events that apply to the place associated with San Francisco Airport:
?place.scope=SFO
placekey
string
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)
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 range during which events were marked as postponed in the system.
E.g. ?postponed.gte=2020-03-01&postponed.lte=2020-03-15
Note when filtering on postponed, events that are not postponed will not be returned.
predicted_end.*
date range
The date range during which events are predicted to end.
E.g. ?predicted_end.gte=2018-12-19&predicted_end.lte=2018-12-19
Note when filtering on predicted_end, events that do not have a predicted_end will not be returned.
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:
accommodationhospitalitytransportation
The format of this parameter name is:
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.
qstart_aroundend_aroundlocation_around
Field Components:
These components correspond to event fields that can be included in relevance. They are not included in relevance by default.
ranklocal_rank
E.g. ?relevance=q,rank,location_around
saved_location.location_id
string
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:
idtitlestartendfirst_seenpredicted_endupdatedranklocal_rankphq_attendancecategorydurationcountrylabelsrelevancepredicted_event_spendpredicted_event_spend_industry.accommodationpredicted_event_spend_industry.hospitalitypredicted_event_spend_industry.transportation
Note when sorting on predicted_endor local_rank (regardless of sort order), events that do not have a predicted_end, local_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 range during which events start.
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 to0d)scale: Distance from origin +/- offset at which the score will equal the decay value (optional, defaults to3d)decay: Score value at thescaledistance (optional, defaults to0.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 range during which events were last modified.
E.g. ?updated.gte=2018-05-01T09:55:00Z
within
area
Mapping File
Below is a CSV of all supported airport codes and their respective place_id.
Response
Response Fields
cancelled
string, null
category
string
The category of the event Possible values:
academicschool-holidayspublic-holidaysobservancespoliticsconferencesexposconcertsfestivalsperforming-artssportscommunitydaylight-savingsairport-delayssevere-weatherdisastersterrorhealth-warnings
E.g. concerts
country
string
deleted_reason
string
The reason why the event was deleted.
Note that this field is only present for events with state deleted.
Possible values:
cancelledduplicateinvalidpostponed
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
end_local
string
The end field is in UTC and end_local is in the local time in the timezone at the events location.
E.g. 2018-12-19T10:00:00
entities
array
An array of Entities linked to the event. Possible types:
event-group- is an entity that logically groups a set of events. There are different event-group Entities which are differentiated by their labels:venue
E.g. Recurring event-group Entity:
E.g. Residency event-group Entity:
E.g. Venue Entity:
first_seen
string, null
id
string
The unique identifier of the event.
E.g. z13B3870YOgv
impact_patterns
array
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 theimpact_typefor that given day. For example, if theimpact_typewasphq_rankthe value would be the PHQ Rank value on the given day. Otherwise, it will reflectphq_attendanceposition- can beleading,event_dayorlagging.leadingare the days before the event occurs,event_dayare the days the event occurs andlaggingare the days after the event has occurred.
The example below is based on an impact_type of phq_rank for severe weather events.
labels
array
The labels associated with the event.
E.g. ["holiday", "holiday-national"]
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
location_confidence_score
number
The Predicted Event location confidence score.
geo
object
address subfield
locality(optional) - indicates the city or town the event occurs incountry_code(required) - 2 letter country codeformatted_address(optional) - a fully formatted address which can include street address, locality, postcode, region and countrypostcode(optional)region(optional) - the region or state at which the event takes place
geometry subfield
Possible geometry.type:
PointPolygonMultiPolygon
E.g.
parent_event
object
E.g.
phq_attendance
number
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.
place_hierarchies
array
E.g.
placekey
string
{address}-{poi}@{where}{address)@{where}@where
postponed
string, null
predicted_end
string
predicted_end_local
string
The predicted_end field is in UTC and predicted_end_local is in the local time in the time zone at the location of the event.
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:00
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.
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:
localitylocaladmincountyregioncountry
E.g. locality
start
string
start_local
string
The start field is in UTC and start_local is in the local time in the timezone at the event location.
E.g. 2018-12-19T10:00:00
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
title
string
The title of the event.
E.g. Katy Perry
updated
string
JSON Schema
Examples
Make sure to properly load your access token from an environment variable or other secure method.
Guides
Below are some guides relevant to this API:
Other Event API Guides
Last updated
Was this helpful?