Search Events

Filters events that are active on or after the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that are active after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that are active on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that are active before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the active.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

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 (see beam.group_id).

This is the best way to filter for events relevant to your business based on your Beam Analysis.

The following parameters are mutually exclusive with beam.analysis_id and cannot be used in the same request:

• within
• category
• country
• local_rank.gt
• local_rank.gte
• local_rank.lt
• local_rank.lte
• local_rank_level
• place.scope
• place.exact
• placekey
• rank.gt
• rank.gte
• rank.lt
• rank.lte
• rank_level
• saved_location.location_id

If beam.group_id is provided the categories will be calculated from the feature importance results of the Analysis Group otherwise the categories will be calculated from the feature importance results of the individual Analysis.

If using beam.group_id the beam.analysis_id is required.

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

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

Default: false

Filters events that were cancelled on or after the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that were cancelled after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that were cancelled on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that were cancelled before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the cancelled.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

A comma-separated list of categories.

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

Example: concerts,sports

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

A comma-separated list of 2-letter country codes.

Example: US

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

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

Example: cancelled,duplicate

Filters events that end on or after the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that end after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that end on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that end before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the end.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

A comma-separated list of Entity identifiers.

Example: XABWvihQAj8TnjvF6WNzLW

Filters events that were first seen in our system on or after the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that were first seen in our system after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that were first seen in our system on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that were first seen in our system before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the first_seen.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

A comma-separated list of Event identifiers.

Example: z13B3870YOgv

Filters events that are predicted to have an impact on or after the specified date.

The Predicted Impact Pattern of events can be larger than the actual event date range.

These parameters work similarly to the active.* parameter, but it uses an industry-specific Predicted Impact Pattern date range of an event where applicable.

You must also specify the industry (see impact.industry).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that are predicted to have an impact after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that are predicted to have an impact on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that are predicted to have an impact before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the impact.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

Selected industry for the Predicted Impact Patterns.

If no industry is selected, impact.* will function effectively the same as active.*.

Example: accommodation

A comma-separated list of labels.

Please note that all event labels are lowercase and that the search is case sensitive.

The label param has been deprecated. Please update your integrations to use phq_label instead.

Example: holiday,observance

Filters events with a Local Rank greater than or equal to the specified value.

Events without a Local Rank will not be returned.

Example: 80

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events with a Local Rank greater than the specified value.

Events without a Local Rank will not be returned.

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events with a Local Rank less than or equal to the specified value.

Events without a Local Rank will not be returned.

Example: 90

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events with a Local Rank less than the specified value.

Events without a Local Rank will not be returned.

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

A comma-separated list of numbers between 1 and 5, corresponding to the 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).

Example: 4,5

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

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.

Filters events with a location confidence score greater than the specified score (exclusive).

Filters events with a location confidence score less than or equal to the specified score.

Filters events with a location confidence score less than the specified score (exclusive).

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.

Default: true

Filters events with a Predicted Attendance greater than or equal to the specified value.

Example: 2000

Filters events with a Predicted Attendance greater than the specified value.

Filters events with a Predicted Attendance less than or equal to the specified value.

Example: 10000

Filters events with a Predicted Attendance less than the specified value.

A comma-separated list of PHQ labels.

PHQ Labels leverage AI and classifier models for more accurate labelling.

Please note that all event labels are lowercase and that the search is case sensitive.

Take a look at PHQ Label Values to get a list of possible values.

Example: agriculture-forestry-and-fisheries,food-and-beverage

Whether to find events with any or all the specified labels.

Default: any

A comma-separated list of PHQ labels to exclude. This will filter for events that do not have the specified labels.

Please note that all event labels are lowercase and that the search is case sensitive.

Example: lifestyle

Whether to exclude events with any or all the specified labels.

Default: any

A comma-separated list of Place IDs and/or IATA (3 character), ICAO (4 character), and UN/LOCODE (5 character) airport codes where the events occur.

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

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.

Example: 5128638,SFO

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

A comma-separated list of Place IDs and/or IATA (3 character), ICAO (4 character), and UN/LOCODE (5 character) airport codes where the events occur.

Results will contain events that apply to the specified place only. E.g. Regional school holidays only.

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

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.

Example: 225@63j-rqb-j7q,@627-s8j-z2k

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events that were marked as postponed on or after the specified date.

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

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that were marked as postponed after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that were marked as postponed on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that were marked as postponed before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the postponed.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

Filters events that are predicted to end on or after the specified date.

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

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that are predicted to end after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that are predicted to end on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that are predicted to end before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the predicted_end.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

Filters events with a Predicted Event Spend (USD) greater or equal to the specified value.

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

Example: 80000

Filters events with a Predicted Event Spend greater than the specified value (exclusive).

Filters events with a Predicted Event Spend less than or equal to the specified value.

Example: 200000

Filters events with a Predicted Event Spend less than the specified value (exclusive).

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 in the same way other range parameters are supported.

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.

Whether or not to include private events. Private events are excluded by default.

Private events are those that have the private field set to true. These events are typically not publicly advertised and may have limited information available. They may be included in the API for specific use cases, but are generally not included in search results by default.

Default: false

A comma-separated list of user identifiers. This filters the events returned to private events that are associated with the specified users.

The private.user_id filter must be used in conjunction with private.include=true or private.include=only.

Example: 12345,67890

A comma-separated list of review statuses for private events. This filters the events returned to private events that have been reviewed by the specified organizations. The private.org_review filter must be used in conjunction with private.include=true or private.include=only.

Example: approved,pending

A full-text search query.

Example: katy perry

Filters events with a PHQ Rank greater than or equal to the specified value.

Example: 80

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events with a PHQ Rank greater than the specified value.

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events with a PHQ Rank less than or equal to the specified value.

Example: 90

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Filters events with a PHQ Rank less than the specified value.

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

A comma-separated list of numbers between 1 and 5, corresponding to the PHQ 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).

Example: 4,5

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

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. Refer to the Saved Locations API for more details on managing locations.

Example: sFlb8HlsLa1j-S4UDEMEkQ

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Comma-separated fields to sort results by. Default: -start (most recent first). Prefix a field name with - to reverse the direction.

• id: sort alphabetically A–Z
• -id: sort alphabetically Z–A
• title: sort alphabetically A–Z
• -title: sort alphabetically Z–A
• start: earliest first (ascending)
• -start: most recent first (descending)
• end: earliest first (ascending)
• -end: most recent first (descending)
• first_seen: oldest first (ascending)
• -first_seen: newest first (descending)
• predicted_end: earliest first (ascending)
• -predicted_end: most recent first (descending)
• updated: oldest first (ascending)
• -updated: newest first (descending)
• rank: highest rank first (descending)
• -rank: lowest rank first (ascending)
• local_rank: highest rank first (descending)
• -local_rank: lowest rank first (ascending)
• phq_attendance: highest attendance first (descending)
• -phq_attendance: lowest attendance first (ascending)
• category: sort alphabetically A–Z
• -category: sort alphabetically Z–A
• duration: shortest first (ascending)
• -duration: longest first (descending)
• country: sort alphabetically A–Z
• -country: sort alphabetically Z–A
• labels: sort alphabetically A–Z
• -labels: sort alphabetically Z–A
• predicted_event_spend: highest spend first (descending)
• -predicted_event_spend: lowest spend first (ascending)
• predicted_event_spend_industry.*: highest spend first (descending)
• -predicted_event_spend_industry.*: lowest spend first (ascending)

Note when sorting on predicted_end or local_rank, events without a value for that field will be placed last.

Example: country,-start

Filters events that start on or after the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that start after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that start on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that start before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the start.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

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.

Filters events with a start date confidence score greater than the specified score (exclusive).

Filters events with a start date confidence score less than or equal to the specified score.

Filters events with a start date confidence score less than the specified score (exclusive).

A comma-separated list of states for the events.

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.

Example: active,deleted

Default: active

Filters events that were last modified on or after the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-01-01

Filters events that were last modified after the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Filters events that were last modified on or before the specified date.

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Example: 2025-02-01

Filters events that were last modified before the specified date (exclusive).

Expected format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.

Specifies the timezone for the updated.* date parameters.

Timezone must be in the TZ Database format (e.g. America/Los_Angeles).

Default: UTC

A geo center and radius in the form {radius}{unit}@{latitude},{longitude}, where the radius unit can be one of: m, km, ft, 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 must 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 we always recommend using our Suggested Radius API to determine the relevant impact zone around your location.

Example: 2.5mi@-36.844480,174.768368

Must not be used in conjunction with beam.analysis_id. These two parameters are mutually exclusive — only one may be provided per request.

Maximum number of results to return per page.

Zero-based index of the first result to return.