# Search Events

{% hint style="info" %}
**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 our [WebApp](https://control.predicthq.com/settings/plans).
{% endhint %}

{% hint style="info" %}
Best practice is to sync event data into your own data store and query your local copy at decision time. Querying the Events API per-request in a live application introduces unnecessary latency.

The preferred sync methods are [Snowflake](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/integrations/third-party-integrations/snowflake) (managed delivery, no pipeline to maintain), [AWS Data Exchange](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/integrations/third-party-integrations/aws-data-exchange) or [SFTP](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/integrations/third-party-integrations/sftp) (file-based), or building your own pipeline via the API using the `updated` parameter - see [Keep Data Updated via API](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/integrations/integration-guides/keep-data-updated-via-api).

For pre-built time-series event-based signals ready for inference, see the [Features API](https://docs.predicthq.com/api/features/get-features).
{% endhint %}

## Search Events

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

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Events API","version":"1.0.0"},"tags":[{"name":"Events API"}],"servers":[{"url":"https://api.predicthq.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"$API_KEY","description":"Enter your PredictHQ API key. The Bearer prefix is added automatically.\n\nWhen calling the API directly, send: `Authorization: Bearer <YOUR_API_KEY>` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"parameters":{"ActiveGteParam":{"in":"query","name":"active.gte","description":"Filters events that are active on or after the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"ActiveGtParam":{"in":"query","name":"active.gt","description":"Filters events that are active after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"ActiveLteParam":{"in":"query","name":"active.lte","description":"Filters events that are active on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"ActiveLtParam":{"in":"query","name":"active.lt","description":"Filters events that are active before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"ActiveTzParam":{"in":"query","name":"active.tz","description":"Specifies the timezone for the `active.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"BeamAnalysisIdParam":{"in":"query","name":"beam.analysis_id","description":"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`).\n\nThis is the best way to filter for events relevant to your business based on your Beam Analysis.","required":false,"schema":{"type":"string"}},"BeamGroupIdParam":{"in":"query","name":"beam.group_id","description":"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.\n\nIf using `beam.group_id` the `beam.analysis_id` is required.","required":false,"schema":{"type":"string"}},"BrandUnsafeExcludeParam":{"in":"query","name":"brand_unsafe.exclude","description":"Whether or not to exclude potentially brand-unsafe events. Potentially brand-unsafe events are included by default.\n\nExamples of brand-unsafe events include content that promotes hate, violence or discrimination, coarse language, content that is sexually suggestive or explicit, etc.\n\nDefault: `false`","required":false,"schema":{"type":"string","enum":["true","false"]}},"CancelledGteParam":{"in":"query","name":"cancelled.gte","description":"Filters events that were cancelled on or after the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`\n","required":false,"schema":{"type":"string","format":"date-time"}},"CancelledGtParam":{"in":"query","name":"cancelled.gt","description":"Filters events that were cancelled after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n","required":false,"schema":{"type":"string","format":"date-time"}},"CancelledLteParam":{"in":"query","name":"cancelled.lte","description":"Filters events that were cancelled on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`\n","required":false,"schema":{"type":"string","format":"date-time"}},"CancelledLtParam":{"in":"query","name":"cancelled.lt","description":"Filters events that were cancelled before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n","required":false,"schema":{"type":"string","format":"date-time"}},"CancelledTzParam":{"in":"query","name":"cancelled.tz","description":"Specifies the timezone for the `cancelled.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"CategoryParam":{"in":"query","name":"category","description":"A comma-separated list of categories.\n\nTake a look at the [Event Categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories) page for an overview of the different categories.\n\nExample: `concerts,sports`","required":false,"schema":{"type":"array","items":{"type":"string","enum":["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"]}},"style":"form","explode":false},"CountryParam":{"in":"query","name":"country","description":"A comma-separated list of 2-letter country codes.\n\nExample: `US`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"DeletedReasonParam":{"in":"query","name":"deleted_reason","description":"A comma-separated list of deleted reasons for the events.\n\nExample: `cancelled,duplicate`","required":false,"schema":{"type":"array","items":{"type":"string","enum":["cancelled","invalid","duplicate","postponed"]}},"style":"form","explode":false},"EndGteParam":{"in":"query","name":"end.gte","description":"Filters events that end on or after the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"EndGtParam":{"in":"query","name":"end.gt","description":"Filters events that end after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"EndLteParam":{"in":"query","name":"end.lte","description":"Filters events that end on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"EndLtParam":{"in":"query","name":"end.lt","description":"Filters events that end before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"EndTzParam":{"in":"query","name":"end.tz","description":"Specifies the timezone for the `end.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"EntityIdParam":{"in":"query","name":"entity.id","description":"A comma-separated list of Entity identifiers.\n\nExample: `XABWvihQAj8TnjvF6WNzLW`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"FirstSeenGteParam":{"in":"query","name":"first_seen.gte","description":"Filters events that were first seen in our system on or after the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"FirstSeenGtParam":{"in":"query","name":"first_seen.gt","description":"Filters events that were first seen in our system after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"FirstSeenLteParam":{"in":"query","name":"first_seen.lte","description":"Filters events that were first seen in our system on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"FirstSeenLtParam":{"in":"query","name":"first_seen.lt","description":"Filters events that were first seen in our system before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"FirstSeenTzParam":{"in":"query","name":"first_seen.tz","description":"Specifies the timezone for the `first_seen.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"IdParam":{"in":"query","name":"id","description":"A comma-separated list of Event identifiers.\n\nExample: `z13B3870YOgv`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"ImpactGteParam":{"in":"query","name":"impact.gte","description":"Filters events that are predicted to have an impact on or after the specified date.\n\nThe Predicted Impact Pattern of events can be larger than the actual event date range.\n\nThese parameters work similarly to the `active.*` parameter, but it uses an industry-specific Predicted Impact Pattern date range of an event where applicable.\n\nYou must also specify the industry (see `impact.industry`).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"ImpactGtParam":{"in":"query","name":"impact.gt","description":"Filters events that are predicted to have an impact after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"ImpactLteParam":{"in":"query","name":"impact.lte","description":"Filters events that are predicted to have an impact on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"ImpactLtParam":{"in":"query","name":"impact.lt","description":"Filters events that are predicted to have an impact before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"ImpactTzParam":{"in":"query","name":"impact.tz","description":"Specifies the timezone for the `impact.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"ImpactIndustryParam":{"in":"query","name":"impact.industry","description":"Selected industry for the Predicted Impact Patterns.\n\nIf no industry is selected, `impact.*` will function effectively the same as `active.*`.\n\nExample: `accommodation`","required":false,"schema":{"type":"string","enum":["accommodation","cpg","tourism","marketing","parking","restaurants","retail","transportation"]}},"LabelParam":{"in":"query","name":"label","description":"A comma-separated list of labels.\n\nPlease note that all event labels are lowercase and that the search is case sensitive.\n\nThe `label` param has been deprecated. Please update your integrations to use `phq_label` instead.\n\nExample: `holiday,observance`","required":false,"deprecated":true,"schema":{"$ref":"#/components/schemas/LegacyLabels"},"style":"form","explode":false},"LocalRankGteParam":{"in":"query","name":"local_rank.gte","description":"Filters events with a Local Rank greater than or equal to the specified value.\n\nEvents without a Local Rank will not be returned.\n\nExample: `80`","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"LocalRankGtParam":{"in":"query","name":"local_rank.gt","description":"Filters events with a Local Rank greater than the specified value.\n\nEvents without a Local Rank will not be returned.","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"LocalRankLteParam":{"in":"query","name":"local_rank.lte","description":"Filters events with a Local Rank less than or equal to the specified value.\n\nEvents without a Local Rank will not be returned.\n\nExample: `90`","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"LocalRankLtParam":{"in":"query","name":"local_rank.lt","description":"Filters events with a Local Rank less than the specified value.\n\nEvents without a Local Rank will not be returned.","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"LocalRankLevelParam":{"in":"query","name":"local_rank_level","description":"A comma-separated list of numbers between 1 and 5, corresponding to the Local Rank levels.\n\nPossible values:\n\n- 1 - Minor (rank between 0 and 20).\n- 2 - Moderate (rank between 21 and 40).\n- 3 - Important (rank between 41 and 60).\n- 4 - Significant (rank between 61 and 80).\n- 5 - Major (rank between 81 and 100).\n\nExample: `4,5`","required":false,"schema":{"type":"array","items":{"type":"integer","enum":[1,2,3,4,5]}},"style":"form","explode":false},"LocationConfidenceScoreGteParam":{"in":"query","name":"location_confidence_score.gte","description":"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.","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"LocationConfidenceScoreGtParam":{"in":"query","name":"location_confidence_score.gt","description":"Filters events with a location confidence score greater than the specified score (exclusive).","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"LocationConfidenceScoreLteParam":{"in":"query","name":"location_confidence_score.lte","description":"Filters events with a location confidence score less than or equal to the specified score.","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"LocationConfidenceScoreLtParam":{"in":"query","name":"location_confidence_score.lt","description":"Filters events with a location confidence score less than the specified score (exclusive).","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"ParentIncludeParam":{"in":"query","name":"parent.include","description":"Whether or not to include parent events / exclude child events.\n\nNote that child events are those events that have a link to a parent event.\nParent events are all the other events, whether they have children or not.\n\nSee the documentation on [umbrella events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events#umbrella-events-beta) for more information on parent and child events.\n\nDefault: `true`","required":false,"schema":{"type":"string","enum":["true","false","only"]}},"PHQAttendanceGteParam":{"in":"query","name":"phq_attendance.gte","description":"Filters events with a Predicted Attendance greater than or equal to the specified value.\n\nExample: `2000`","required":false,"schema":{"type":"integer","minimum":0}},"PHQAttendanceGtParam":{"in":"query","name":"phq_attendance.gt","description":"Filters events with a Predicted Attendance greater than the specified value.","required":false,"schema":{"type":"integer","minimum":0}},"PHQAttendanceLteParam":{"in":"query","name":"phq_attendance.lte","description":"Filters events with a Predicted Attendance less than or equal to the specified value.\n\nExample: `10000`","required":false,"schema":{"type":"integer","minimum":0}},"PHQAttendanceLtParam":{"in":"query","name":"phq_attendance.lt","description":"Filters events with a Predicted Attendance less than the specified value.","required":false,"schema":{"type":"integer","minimum":0}},"PHQLabelParam":{"in":"query","name":"phq_label","description":"A comma-separated list of PHQ labels.\n\nPHQ Labels leverage AI and classifier models for more accurate labelling.\n\nPlease note that all event labels are lowercase and that the search is case sensitive.\n\nTake a look at [PHQ Label Values](https://docs.predicthq.com/getting-started/predicthq-data/labels#phq-label-values) to get a list of possible values.\n\nExample: `agriculture-forestry-and-fisheries,food-and-beverage`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"PHQLabelOpParam":{"in":"query","name":"phq_label.op","description":"Whether to find events with `any` or `all` the specified labels.\n\nDefault: `any`","required":false,"schema":{"type":"string","enum":["all","any"]}},"PHQLabelExcludeParam":{"in":"query","name":"phq_label.exclude","description":"A comma-separated list of PHQ labels to exclude. This will filter for events that do not have the specified labels.\n\nPlease note that all event labels are lowercase and that the search is case sensitive.\n\nExample: `lifestyle`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"PHQLabelExcludeOpParam":{"in":"query","name":"phq_label.exclude.op","description":"Whether to exclude events with `any` or `all` the specified labels.\n\nDefault: `any`","required":false,"schema":{"type":"string","enum":["all","any"]}},"PlaceScopeParam":{"in":"query","name":"place.scope","description":"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.\n\nA CSV file of all supported airport codes and their respective Place IDs is available to download.\n\nResults 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.\n\nExample: `5128638,SFO`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"PlaceExactParam":{"in":"query","name":"place.exact","description":"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.\n\nResults will contain events that apply to the specified place only. E.g. Regional school holidays only.","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"PlacekeyParam":{"in":"query","name":"placekey","description":"A comma-separated list of Placekeys (See [placekey.io](https://www.placekey.io/)). Returns events that have a Placekey value matching this filter.\n\nThere are 2 parts to a Placekey: `what@where`\n\n- `what` Contains 2 part in the form `{address}-{poi}`.\n  - The first part represents an address.\n  - The second part represents a Point Of Interest (E.g. named venue). This will be missing on locations that only have addresses\n- `where` An H3 hexagon index (resolution 10) of the event.\n\nThis 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:\n\n- `{address}-{poi}@{where}` - only returns events with a full matching placekey (an exact match)\n- `{address}@{where}` - matches events where the the address and where part match (even if poi is different)\n- `@{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](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-placekey) for more details.\n\n\nNote that Placekey applies to our attended event categories. Some events do not contain a Placekey.\n\nExample: `225@63j-rqb-j7q,@627-s8j-z2k`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"PostponedGteParam":{"in":"query","name":"postponed.gte","description":"Filters events that were marked as postponed on or after the specified date.\n\nNote when filtering on postponed, events that are not postponed will not be returned.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"PostponedGtParam":{"in":"query","name":"postponed.gt","description":"Filters events that were marked as postponed after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"PostponedLteParam":{"in":"query","name":"postponed.lte","description":"Filters events that were marked as postponed on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"PostponedLtParam":{"in":"query","name":"postponed.lt","description":"Filters events that were marked as postponed before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"PostponedTzParam":{"in":"query","name":"postponed.tz","description":"Specifies the timezone for the `postponed.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"PredictedEndGteParam":{"in":"query","name":"predicted_end.gte","description":"Filters events that are predicted to end on or after the specified date.\n\nNote when filtering on postponed, events that are not postponed will not be returned.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"PredictedEndGtParam":{"in":"query","name":"predicted_end.gt","description":"Filters events that are predicted to end after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"PredictedEndLteParam":{"in":"query","name":"predicted_end.lte","description":"Filters events that are predicted to end on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"PredictedEndLtParam":{"in":"query","name":"predicted_end.lt","description":"Filters events that are predicted to end before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"PredictedEndTzParam":{"in":"query","name":"predicted_end.tz","description":"Specifies the timezone for the `predicted_end.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"PredictedEventSpendGteParam":{"in":"query","name":"predicted_event_spend.gte","description":"Filters events with a Predicted Event Spend (USD) greater or equal to the specified value.\n\nNote: When using this filter events that do not have a  predicted_event_spend  will not be returned.\n\nExample: `80000`","required":false,"schema":{"type":"integer","minimum":0}},"PredictedEventSpendGtParam":{"in":"query","name":"predicted_event_spend.gt","description":"Filters events with a Predicted Event Spend greater than the specified value (exclusive).","required":false,"schema":{"type":"integer","minimum":0}},"PredictedEventSpendLteParam":{"in":"query","name":"predicted_event_spend.lte","description":"Filters events with a Predicted Event Spend less than or equal to the specified value.\n\nExample: `200000`","required":false,"schema":{"type":"integer","minimum":0}},"PredictedEventSpendLtParam":{"in":"query","name":"predicted_event_spend.lt","description":"Filters events with a Predicted Event Spend less than the specified value (exclusive).","required":false,"schema":{"type":"integer","minimum":0}},"PredictedEventSpendIndustryParam":{"in":"query","name":"predicted_event_spend_industry.<industry>.<suffix>","description":"The Predicted Event Spend for a given industry in USD.\n\nSupported industries:\n- accommodation\n- hospitality\n- transportation\n\nThe format of this parameter name is: `predicted_event_spend_industry.<industry>.<suffix>`\n\nSupports `gt`, `gte`, `lt` and `lte` suffixes in the same way other range parameters are supported.\n\nPlease note that use of a suffix is required.\n\nNote: When using this filter events that do not have a `predicted_event_spend` will not be returned.","required":false,"schema":{"type":"integer"}},"PrivateIncludeParam":{"in":"query","name":"private.include","description":"Whether or not to include private events. Private events are excluded by default.\n\nPrivate 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.\n\nDefault: `false`","required":false,"schema":{"type":"string","enum":["true","false","only"]}},"PrivateUserIdParam":{"in":"query","name":"private.user_id","description":"A comma-separated list of user identifiers. This filters the events returned to private events that are associated with the specified users.\n\nThe `private.user_id` filter must be used in conjunction with `private.include=true` or `private.include=only`.\n\nExample: `12345,67890`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"PrivateOrgReviewParam":{"in":"query","name":"private.org_review","description":"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.\nThe `private.org_review` filter must be used in conjunction with `private.include=true` or `private.include=only`.\n\nExample: `approved,pending`","required":false,"schema":{"type":"array","items":{"type":"string","enum":["approved","pending","rejected"]}},"style":"form","explode":false},"QParam":{"in":"query","name":"q","description":"A full-text search query.\n\nExample: `katy perry`","schema":{"type":"string"}},"RankGteParam":{"in":"query","name":"rank.gte","description":"Filters events with a PHQ Rank greater than or equal to the specified value.\n\nExample: `80`","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"RankGtParam":{"in":"query","name":"rank.gt","description":"Filters events with a PHQ Rank greater than the specified value.","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"RankLteParam":{"in":"query","name":"rank.lte","description":"Filters events with a PHQ Rank less than or equal to the specified value.\n\nExample: `90`","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"RankLtParam":{"in":"query","name":"rank.lt","description":"Filters events with a PHQ Rank less than the specified value.","required":false,"schema":{"type":"integer","maximum":100,"minimum":0}},"RankLevelParam":{"in":"query","name":"rank_level","description":"A comma-separated list of numbers between 1 and 5, corresponding to the PHQ Rank levels.\n\nPossible values:\n\n- 1 - Minor (rank between 0 and 20).\n- 2 - Moderate (rank between 21 and 40).\n- 3 - Important (rank between 41 and 60).\n- 4 - Significant (rank between 61 and 80).\n- 5 - Major (rank between 81 and 100).\n\nExample: `4,5`","required":false,"schema":{"type":"array","items":{"type":"integer","enum":[1,2,3,4,5]}},"style":"form","explode":false},"SavedLocationLocationIdParam":{"in":"query","name":"saved_location.location_id","description":"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.\n\nExample: `sFlb8HlsLa1j-S4UDEMEkQ`","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false},"SortParam":{"in":"query","name":"sort","description":"A comma-separated list of fields to sort results by. The default is `-start`.\n\nPrefix the field name with `-` for reverse order.\n\nNote when sorting on `predicted_end` or `local_rank` (regardless of sort order), events that do not have a `predicted_end`, `local_rank` will be placed last.\n\nExample: `country,-start`","required":false,"schema":{"type":"array","items":{"type":"string","enum":["id","title","start","end","first_seen","predicted_end","updated","rank","local_rank","phq_attendance","category","duration","country","labels","predicted_event_spend","predicted_event_spend_industry.accommodation","predicted_event_spend_industry.hospitality","predicted_event_spend_industry.transportation"]}},"style":"form","explode":false},"StartGteParam":{"in":"query","name":"start.gte","description":"Filters events that start on or after the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"StartGtParam":{"in":"query","name":"start.gt","description":"Filters events that start after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"StartLteParam":{"in":"query","name":"start.lte","description":"Filters events that start on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"StartLtParam":{"in":"query","name":"start.lt","description":"Filters events that start before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"StartTzParam":{"in":"query","name":"start.tz","description":"Specifies the timezone for the `start.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"StartDateConfidenceScoreGteParam":{"in":"query","name":"start_date_confidence_score.gte","description":"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.","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"StartDateConfidenceScoreGtParam":{"in":"query","name":"start_date_confidence_score.gt","description":"Filters events with a start date confidence score greater than the specified score (exclusive).","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"StartDateConfidenceScoreLteParam":{"in":"query","name":"start_date_confidence_score.lte","description":"Filters events with a start date confidence score less than or equal to the specified score.","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"StartDateConfidenceScoreLtParam":{"in":"query","name":"start_date_confidence_score.lt","description":"Filters events with a start date confidence score less than the specified score (exclusive).","required":false,"schema":{"type":"integer","maximum":5,"minimum":1}},"StateParam":{"in":"query","name":"state","description":"A comma-separated list of states for the events.\n\nThis 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.\n\nExample: `active,deleted`\n\nDefault: `active`","required":false,"schema":{"type":"array","items":{"type":"string","enum":["active","deleted","predicted"]}},"style":"form","explode":false},"UpdatedGteParam":{"in":"query","name":"updated.gte","description":"Filters events that were last modified on or after the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date-time"}},"UpdatedGtParam":{"in":"query","name":"updated.gt","description":"Filters events that were last modified after the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"UpdatedLteParam":{"in":"query","name":"updated.lte","description":"Filters events that were last modified on or before the specified date.\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.\n\nExample: `2025-02-01`","required":false,"schema":{"type":"string","format":"date-time"}},"UpdatedLtParam":{"in":"query","name":"updated.lt","description":"Filters events that were last modified before the specified date (exclusive).\n\nExpected format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`.","required":false,"schema":{"type":"string","format":"date-time"}},"UpdatedTzParam":{"in":"query","name":"updated.tz","description":"Specifies the timezone for the `updated.*` date parameters.\n\nTimezone must be in the [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `America/Los_Angeles`).\n\nDefault: `UTC`","required":false,"schema":{"type":"string"}},"WithinParam":{"in":"query","name":"within","description":"A geo center and radius in the form `{radius}{unit}@{latitude},{longitude}`, where the radius unit can be one of: `m`, `km`, `ft`, `mi`.\n\nWhen using the units of `km` and `mi` you can enter whole numbers or floats e.g. `5mi`, `1.5km` or `1.2mi`.\nWhen using the units `ft` or `m` you must enter whole numbers (you cannot enter a fraction of a meter or foot).\n\nNote that results may contain events that apply to a parent scope of the specified area.\n\nNote we always recommend using our Suggested Radius API to determine the relevant impact zone around your location.\n\nExample: `2.5mi@-36.844480,174.768368`","required":false,"schema":{"type":"string","pattern":"^(?:(?:[1-9]\\d*(?:\\.\\d+)?(km|mi))|(?:[1-9]\\d*(m|ft)))@-?\\d+(?:\\.\\d+)?,\\-?\\d+(?:\\.\\d+)?$"}},"LimitParam":{"name":"limit","in":"query","description":"Limit the number of results.","required":false,"schema":{"type":"integer","default":10}},"OffsetParam":{"name":"offset","in":"query","description":"Offset the results.","required":false,"schema":{"type":"integer","default":0}}},"schemas":{"LegacyLabels":{"description":"Legacy labels to further categorise the event.","type":"array","items":{"type":"string","enum":["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"]},"deprecated":true,"title":"Legacy Labels"},"EventsResponse":{"description":"Paginated response containing events.","type":"object","properties":{"count":{"description":"The total number of results.","type":"integer","minimum":0},"overflow":{"description":"Indicates if there are more results than the subscription allows.","type":"boolean","default":false},"previous":{"type":"string"},"next":{"type":"string"},"results":{"description":"List of event records.","type":"array","items":{"$ref":"#/components/schemas/Event"}}},"required":["count","next","previous","overflow","results"],"title":"Events Response"},"Event":{"description":"An individual event object.","type":"object","properties":{"brand_safe":{"description":"Indicates whether or not the event is considered \"brand safe\".","type":"boolean"},"cancelled":{"description":"The date the event was set to cancelled in the system in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nDates are in UTC.\n\nThis 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.","type":["string","null"],"format":"date-time"},"category":{"description":"The category of the event.","$ref":"#/components/schemas/EventCategory"},"country":{"description":"The country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.\nNote 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.","type":"string"},"deleted_reason":{"description":"The reason why the event was deleted.\n\nNote that this field is only present for events with state `deleted`.","type":"string","enum":["cancelled","duplicate","invalid","postponed"]},"description":{"description":"A description of the event.","type":["string","null"]},"duplicate_of_id":{"description":"The `id` of the active event this event is a duplicate of.\n\nNote that this field is only present for deleted events with `deleted_reason` set to `duplicate`.","type":["string","null"]},"duration":{"description":"The duration of the event in seconds.","type":"integer"},"end":{"description":"The end date of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nAll 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.","type":["string","null"],"format":"date-time"},"end_local":{"description":"The end date in local time of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nThe `end` field is in UTC and `end_local` is in the local time at the events location.","type":["string","null"],"format":"date-time"},"entities":{"description":"An array of Entities linked to the event.\n\nRead the [Entities data guide](https://docs.predicthq.com/getting-started/predicthq-data/entities) for more info.","type":"array","items":{"type":"object","required":["entity_id","name","type"],"properties":{"entity_id":{"type":"string"},"type":{"type":"string","enum":["airport","event-group","organization","person","venue"]},"labels":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"description":{"type":"string"},"category":{"$ref":"#/components/schemas/EventCategory"},"formatted_address":{"type":"string"},"timezone":{"type":"string"},"recurring":{"type":"object","properties":{"ical":{"type":"string"}},"required":["ical"]}}}},"first_seen":{"description":"The date the event first entered our dataset in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Dates are in UTC. This value should not be considered an event announcement date.","type":["string"],"format":"date-time"},"id":{"description":"The unique identifier of the event.","type":"string"},"impact_patterns":{"description":"This field shows the Predicted Impact Patterns for leading days (days before the event), lagging days (days after an event), and the days the event occurs. See [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns) for more details.\n\nimpact_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:","type":"array","items":{"type":"object","required":["vertical","impact_type","impacts"],"properties":{"vertical":{"description":"The industry vertical the impact pattern applies to.","type":"string","enum":["accommodation","retail","hospitality"]},"impact_type":{"description":"Indicates the type of impact shown in the impact pattern. Currently, the supported types are phq_rank,  phq_attendance, and phq_impact. \n\nIf 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. \n\nIf impact_type is phq_impact then the impact values per day reflect phq_impact which represents the predicted impact and demand changes on specific verticals (accommodation, hospitality, retail).","type":"string","enum":["phq_rank","phq_attendance","phq_impact"]},"impacts":{"type":"array","items":{"type":"object","required":["date_local","value","position"],"properties":{"date_local":{"description":"The date in the local timezone of the event.","type":"string","format":"date"},"value":{"description":"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`.","type":"integer"},"position":{"description":"- `leading` are the days before the event occurs.\n- `event_day` are the days the event occurs.\n- `lagging` are the days after the event has occurred.","type":"string","enum":["leading","event_day","lagging"]}}}}}}},"labels":{"$ref":"#/components/schemas/LegacyLabels"},"local_rank":{"description":"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.\n\nIf `local_rank` is not intended to be available for an event, this field will be `null`.","type":"integer","maximum":100,"minimum":0},"location":{"description":"A 2-tuple representing the geo location of the event. Note that the longitude/latitude coordinates use the [GeoJSON](https://geojson.org/) order [lon, lat].\n\nPlease use the `geo` field instead of this field.","type":"array","items":{"type":"number"},"deprecated":true,"maxItems":2,"minItems":2},"location_confidence_score":{"description":"The Predicted Event location confidence score.","type":"integer","maximum":5,"minimum":1},"geo":{"description":"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).","oneOf":[{"type":"object","properties":{"geometry":{"$ref":"#/components/schemas/Geometry"},"placekey":{"description":"The Placekey (See [placekey.io](https://www.placekey.io/)) reflects the location of an event in the format what@where. Placekey is part of the geo field for an event.\n\nPossible formats:\n- `{address}-{poi}@{where}`\n- `{address)@{where}`\n- `@where`\n\nSome events do not contain a Placekey.","type":"string"},"address":{"oneOf":[{"type":"object","required":["country_code"],"properties":{"country_code":{"type":"string"},"formatted_address":{"type":"string"},"locality":{"type":"string"},"region":{"type":"string"},"postcode":{"type":"string"}}},{"type":"null"}]}}},{"type":"null"}]},"parent_event":{"description":"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).\n\nSee [umbrella events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events#umbrella-events-beta) for details on this field and details on what umbrella events are.\n\nNote that this field shows if a child event has a parent id. It does not indicate if a parent event has child events.","type":"object","properties":{"parent_event_id":{"description":"The parent_event_id refers to the id of the event that is the parent for the current event.","type":"string"}},"required":["parent_event_id"]},"phq_attendance":{"description":"A numerical value that reflects the predicted attendance for supported attendance-based categories.\n\nThis 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.\n\nSee [Handling multi-day and Umbrella events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events) for more details.","type":"integer"},"phq_labels":{"description":"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.0\n\nPHQ Labels leverage AI 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.\n\nTake a look at [PHQ Label Values](https://docs.predicthq.com/getting-started/predicthq-data/labels#phq-label-values) to see a list of possible values that could be in phq_labels.label.","type":"array","items":{"type":"object","required":["label","weight"],"properties":{"label":{"type":"string"},"weight":{"type":"number","maximum":1,"minimum":0}}}},"place_hierarchies":{"description":"An array of place hierarchies for the event. Each hierarchy is an array of place IDs. 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.\n\nFor example, a hierarchy might contain the following places in this order: `Earth > Europe > United Kingdom > England > Nottingham`\n\nNote that the place_hierarchies value can be an empty array in some cases.","type":"array","items":{"type":"array","items":{"type":"string"}}},"postponed":{"description":"The date the event was set to postponed in the system in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Dates are in UTC.\n\nThis 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.","type":"string","format":"date-time"},"predicted_end":{"description":"The predicted end date of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nPredicted 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.\n\nThis field will only be present if an actual `end` time is not available for an event and we have a predicted end time.","type":"string","format":"date-time"},"predicted_end_local":{"description":"The predicted end date in the local time of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nThe `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.\n\nThis field will only be present if an actual `end` time is not available for an event and we have a predicted end time.","type":"string","format":"date-time"},"predicted_event_spend":{"description":"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.","type":"integer"},"predicted_event_spend_industries":{"description":"The Predicted Event Spend for each supported industry in USD.","type":"object","properties":{"accommodation":{"description":"The consumer spend predicted to be attributed to hotels and hosts.","type":"integer"},"hospitality":{"description":"The consumer spend predicted to be attributed to food and beverage.","type":"integer"},"transportation":{"description":"The consumer spend predicted to be attributed to ground-based transportation as a means of getting to and from the event.","type":"integer"}}},"rank":{"description":"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.","type":"integer","maximum":100,"minimum":0},"scope":{"description":"The geographical scope the events apply to.","type":"string","enum":["locality","localadmin","county","region","country"]},"start":{"description":"The start date of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nAll 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.\n\nIf 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.","type":["string","null"],"format":"date-time"},"start_local":{"description":"The local start date of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nThe `start` field is in UTC and `start_local` is in the local time in the timezone at the event location.","type":["string","null"],"format":"date-time"},"start_date_confidence_score":{"description":"The Predicted Event start date confidence score.","type":"integer","maximum":5,"minimum":1},"state":{"description":"The publication state of the event.\n\nPossible values:\n- `active`: the event is published and valid.\n- `deleted`: the event was removed, either because it was cancelled or is a duplicate.\n- `predicted`: events that have an unconfirmed start time i.e for which the exact time the event begins is not yet known.","type":"string","enum":["active","deleted","predicted"]},"timezone":{"description":"The time zone of the event in [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format. This is helpful so you know which time zone to convert the dates to (if needed).\n\nIf 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.","type":"string"},"title":{"description":"The title of the event.","type":"string"},"updated":{"description":"The last modification date of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. All dates are in UTC.","type":"string","format":"date-time"}},"required":["category","country","description","duration","end","entities","first_seen","id","place_hierarchies","rank","geo","start","state","timezone","title","updated"]},"EventCategory":{"description":"Event categories.","type":"string","enum":["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"],"title":"Event Category"},"Geometry":{"oneOf":[{"title":"GeoJSON Point","type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","const":"Point"},"coordinates":{"type":"array","items":{"type":"number"},"maxItems":2,"minItems":2}}},{"title":"GeoJSON MultiPoint","type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","const":"MultiPoint"},"coordinates":{"type":"array","items":{"type":"array","minItems":2,"items":{"type":"number"}}}}},{"title":"GeoJSON LineString","type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","const":"LineString"},"coordinates":{"type":"array","items":{"type":"array","minItems":2,"items":{"type":"number"}},"minItems":2}}},{"title":"GeoJSON MultiLineString","type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","const":"MultiLineString"},"coordinates":{"type":"array","items":{"type":"array","minItems":2,"items":{"type":"array","minItems":2,"items":{"type":"number"}}}}}},{"title":"GeoJSON Polygon","type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","const":"Polygon"},"coordinates":{"type":"array","items":{"type":"array","minItems":4,"items":{"type":"array","minItems":2,"items":{"type":"number"}}}}}},{"title":"GeoJSON MultiPolygon","type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","const":"MultiPolygon"},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","minItems":4,"items":{"type":"array","minItems":2,"items":{"type":"number"}}}}}}}],"title":"GeoJSON Geometry"}}},"paths":{"/v1/events/":{"get":{"operationId":"searchEvents","summary":"Search Events","description":"Search for events happening in a location and date range. Use our extensive filters to narrow down your results.","parameters":[{"$ref":"#/components/parameters/ActiveGteParam"},{"$ref":"#/components/parameters/ActiveGtParam"},{"$ref":"#/components/parameters/ActiveLteParam"},{"$ref":"#/components/parameters/ActiveLtParam"},{"$ref":"#/components/parameters/ActiveTzParam"},{"$ref":"#/components/parameters/BeamAnalysisIdParam"},{"$ref":"#/components/parameters/BeamGroupIdParam"},{"$ref":"#/components/parameters/BrandUnsafeExcludeParam"},{"$ref":"#/components/parameters/CancelledGteParam"},{"$ref":"#/components/parameters/CancelledGtParam"},{"$ref":"#/components/parameters/CancelledLteParam"},{"$ref":"#/components/parameters/CancelledLtParam"},{"$ref":"#/components/parameters/CancelledTzParam"},{"$ref":"#/components/parameters/CategoryParam"},{"$ref":"#/components/parameters/CountryParam"},{"$ref":"#/components/parameters/DeletedReasonParam"},{"$ref":"#/components/parameters/EndGteParam"},{"$ref":"#/components/parameters/EndGtParam"},{"$ref":"#/components/parameters/EndLteParam"},{"$ref":"#/components/parameters/EndLtParam"},{"$ref":"#/components/parameters/EndTzParam"},{"$ref":"#/components/parameters/EntityIdParam"},{"$ref":"#/components/parameters/FirstSeenGteParam"},{"$ref":"#/components/parameters/FirstSeenGtParam"},{"$ref":"#/components/parameters/FirstSeenLteParam"},{"$ref":"#/components/parameters/FirstSeenLtParam"},{"$ref":"#/components/parameters/FirstSeenTzParam"},{"$ref":"#/components/parameters/IdParam"},{"$ref":"#/components/parameters/ImpactGteParam"},{"$ref":"#/components/parameters/ImpactGtParam"},{"$ref":"#/components/parameters/ImpactLteParam"},{"$ref":"#/components/parameters/ImpactLtParam"},{"$ref":"#/components/parameters/ImpactTzParam"},{"$ref":"#/components/parameters/ImpactIndustryParam"},{"$ref":"#/components/parameters/LabelParam"},{"$ref":"#/components/parameters/LocalRankGteParam"},{"$ref":"#/components/parameters/LocalRankGtParam"},{"$ref":"#/components/parameters/LocalRankLteParam"},{"$ref":"#/components/parameters/LocalRankLtParam"},{"$ref":"#/components/parameters/LocalRankLevelParam"},{"$ref":"#/components/parameters/LocationConfidenceScoreGteParam"},{"$ref":"#/components/parameters/LocationConfidenceScoreGtParam"},{"$ref":"#/components/parameters/LocationConfidenceScoreLteParam"},{"$ref":"#/components/parameters/LocationConfidenceScoreLtParam"},{"$ref":"#/components/parameters/ParentIncludeParam"},{"$ref":"#/components/parameters/PHQAttendanceGteParam"},{"$ref":"#/components/parameters/PHQAttendanceGtParam"},{"$ref":"#/components/parameters/PHQAttendanceLteParam"},{"$ref":"#/components/parameters/PHQAttendanceLtParam"},{"$ref":"#/components/parameters/PHQLabelParam"},{"$ref":"#/components/parameters/PHQLabelOpParam"},{"$ref":"#/components/parameters/PHQLabelExcludeParam"},{"$ref":"#/components/parameters/PHQLabelExcludeOpParam"},{"$ref":"#/components/parameters/PlaceScopeParam"},{"$ref":"#/components/parameters/PlaceExactParam"},{"$ref":"#/components/parameters/PlacekeyParam"},{"$ref":"#/components/parameters/PostponedGteParam"},{"$ref":"#/components/parameters/PostponedGtParam"},{"$ref":"#/components/parameters/PostponedLteParam"},{"$ref":"#/components/parameters/PostponedLtParam"},{"$ref":"#/components/parameters/PostponedTzParam"},{"$ref":"#/components/parameters/PredictedEndGteParam"},{"$ref":"#/components/parameters/PredictedEndGtParam"},{"$ref":"#/components/parameters/PredictedEndLteParam"},{"$ref":"#/components/parameters/PredictedEndLtParam"},{"$ref":"#/components/parameters/PredictedEndTzParam"},{"$ref":"#/components/parameters/PredictedEventSpendGteParam"},{"$ref":"#/components/parameters/PredictedEventSpendGtParam"},{"$ref":"#/components/parameters/PredictedEventSpendLteParam"},{"$ref":"#/components/parameters/PredictedEventSpendLtParam"},{"$ref":"#/components/parameters/PredictedEventSpendIndustryParam"},{"$ref":"#/components/parameters/PrivateIncludeParam"},{"$ref":"#/components/parameters/PrivateUserIdParam"},{"$ref":"#/components/parameters/PrivateOrgReviewParam"},{"$ref":"#/components/parameters/QParam"},{"$ref":"#/components/parameters/RankGteParam"},{"$ref":"#/components/parameters/RankGtParam"},{"$ref":"#/components/parameters/RankLteParam"},{"$ref":"#/components/parameters/RankLtParam"},{"$ref":"#/components/parameters/RankLevelParam"},{"$ref":"#/components/parameters/SavedLocationLocationIdParam"},{"$ref":"#/components/parameters/SortParam"},{"$ref":"#/components/parameters/StartGteParam"},{"$ref":"#/components/parameters/StartGtParam"},{"$ref":"#/components/parameters/StartLteParam"},{"$ref":"#/components/parameters/StartLtParam"},{"$ref":"#/components/parameters/StartTzParam"},{"$ref":"#/components/parameters/StartDateConfidenceScoreGteParam"},{"$ref":"#/components/parameters/StartDateConfidenceScoreGtParam"},{"$ref":"#/components/parameters/StartDateConfidenceScoreLteParam"},{"$ref":"#/components/parameters/StartDateConfidenceScoreLtParam"},{"$ref":"#/components/parameters/StateParam"},{"$ref":"#/components/parameters/UpdatedGteParam"},{"$ref":"#/components/parameters/UpdatedGtParam"},{"$ref":"#/components/parameters/UpdatedLteParam"},{"$ref":"#/components/parameters/UpdatedLtParam"},{"$ref":"#/components/parameters/UpdatedTzParam"},{"$ref":"#/components/parameters/WithinParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/OffsetParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}}},"tags":["Events API"]}}}}
```

## Examples

{% tabs %}
{% tab title="python sdk" %}
Make sure to properly load your access token from an environment variable or other secure method.

```python
from predicthq import Client

phq = Client(access_token="$ACCESS_TOKEN")

for event in phq.events.search(
    place__scope=[5809844],
    category=["conferences", "expos", "concerts", "festivals", "performing-arts", "community", "sports"],
    active__gte="2025-02-01",
    active__lte="2025-04-01",
):
    print(event.rank, event.category, event.title, event.start.strftime("%Y-%m-%d"))

```

{% endtab %}

{% tab title="python" %}
Make sure to properly load your access token from an environment variable or other secure method.

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "category": "conferences,expos,concerts,festivals,performing-arts,community,sports",
        "place.scope": "5809844",
        "active.gte": "2025-03-01",
        "active.lte": "2025-04-01"
    }
)

print(response.json())
```

{% endtab %}

{% tab title="curl" %}
Make sure to properly load your access token from an environment variable or other secure method.

```bash
curl -X GET "https://api.predicthq.com/v1/events/?category=conferences,expos,concerts,festivals,performing-arts,community,sports&place.scope=5809844&active.gte=2025-03-01&active.lte=2025-04-01" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
```

{% endtab %}
{% endtabs %}

## OpenAPI Spec

The OpenAPI spec for Events API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Events+API).

## Guides

{% hint style="info" %}
**Airport Codes Mapping File**\
Airport codes are mapped to Place IDs. The current mapping of airport code to Place ID can be [found here](https://github.com/predicthq/api-specs/blob/main/data/airport-codes.csv).
{% endhint %}

Below are some guides relevant to this API:

* [Geolocation Guides](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/geolocation-guides)
* [Date and Time Guides](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/date-and-time-guides)
* Other [Events API Guides](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/events-api-guides)