Introducing the Forecasts API — Event-driven forecasts for precise demand planning. Fast, accurate, and easy to run.
Explore Now
LogoLogo
Visit websiteWebAppGet DemoTry for Free
  • Introduction
  • Swagger UI
  • Loop
  • System Status
  • Getting Started
    • API Quickstart
    • Data Science Notebooks
    • PredictHQ Data
      • Data Accuracy
      • Event Categories
        • Attendance-Based Events
        • Non-Attendance-Based Events
        • Unscheduled Events
        • Live TV Events
      • Labels
      • Entities
      • Ranks
        • PHQ Rank
        • Local Rank
        • Aviation Rank
      • Predicted Attendance
      • Predicted End Times
      • Predicted Event Spend
      • Predicted Events
      • Predicted Impact Patterns
    • Guides
      • Geolocation Guides
        • Overview
        • Searching by Location
          • Find Events by Latitude/Longitude and Radius
          • Find Events by Place ID
          • Find Events by IATA Code
          • Find Events by Country Code
          • Find Events by Placekey
          • Working with Location-Based Subscriptions
        • Understanding Place Hierarchies
        • Working with Polygons
        • Join Events using Placekey
      • Date and Time Guides
        • Working with Recurring Events
        • Working with Multi-day and Umbrella Events
        • Working with Dates, Times and Timezones
      • Events API Guides
        • Understanding Relevance Field in Event Results
        • Attendance-Based Events Notebooks
        • Non-Attendance-Based Events Notebooks
        • Severe Weather Events Notebooks
        • Academic Events Notebooks
        • Working with Venues Notebook
      • Features API Guides
        • Increase Accuracy with the Features API
        • Get ML Features
        • Demand Forecasting with Event Features
      • Forecasts API Guides
        • Getting Started with Forecasts API
        • Understanding Forecast Accuracy Metrics
        • Troubleshooting Guide for Forecasts API
      • Live TV Event Guides
        • Find Broadcasts by County Place ID
        • Find Broadcasts by Latitude and Longitude
        • Find all Broadcasts for an Event
        • Find Broadcasts for Specific Sport Types
        • Aggregating Live TV Events
        • Live TV Events Notebooks
      • Beam Guides
        • ML Features by Location
        • ML Features by Group
      • Demand Surge API Guides
        • Demand Surge Notebook
      • Guide to Protecting PredictHQ Data
      • Streamlit Demo Apps
      • Guide to Bulk Export Data via the WebApp
      • Industry-Specific Event Filters
      • Tutorials
        • Filtering and Finding Relevant Events
        • Improving Demand Forecasting Models with Event Features
        • Using Event Data in Power BI
        • Using Event Data in Tableau
        • Connecting to PredictHQ APIs with Microsoft Excel
        • Loading Event Data into a Data Warehouse
        • Displaying Events in a Heatmap Calendar
        • Displaying Events on a Map
    • Tutorials by Use Case
      • Demand Forecasting with ML Models
      • Dynamic Pricing
      • Inventory Management
      • Workforce Optimization
      • Visualization and Insights
  • Integrations
    • Integration Guides
      • Keep Data Updated via API
      • Integrate with Beam
      • Integrate with Loop Links
    • Third-Party Integrations
      • Receive Data via Snowflake
        • Example SQL Queries for Snowflake
        • Snowflake Data Science Guide
          • Snowpark Method Guide
          • SQL Method Guide
      • Receive Data via AWS Data Exchange
        • CSV/Parquet Data Structure for ADX
        • NDJSON Data Structure for ADX
      • Integrate with Databricks
      • Integrate with Tableau
      • Integrate with a Demand Forecast in PowerBI
      • Google Cloud BigQuery
    • PredictHQ SDKs
      • Python SDK
      • Javascript SDK
  • API Reference
    • API Overview
      • Authenticating
      • API Specs
      • Rate Limits
      • Pagination
      • API Changes
      • Attribution
      • Troubleshooting
    • Events
      • Search Events
      • Get Event Counts
    • Broadcasts
      • Search Broadcasts
      • Get Broadcasts Count
    • Features
      • Get ML Features
    • Forecasts
      • Models
        • Create Model
        • Update Model
        • Replace Model
        • Delete Model
        • Search Models
        • Get Model
        • Train Model
      • Demand Data
        • Upload Demand Data
        • Get Demand Data
      • Forecasts
        • Get Forecast
      • Algorithms
        • Get Algorithms
    • Beam
      • Create an Analysis
      • Upload Demand Data
      • Search Analyses
      • Get an Analysis
      • Update an Analysis
      • Partially Update an Analysis
      • Get Correlation Results
      • Get Feature Importance
      • Refresh an Analysis
      • Delete an Analysis
      • Analysis Groups
        • Create an Analysis Group
        • Get an Analysis Group
        • Search Analysis Groups
        • Update an Analysis Group
        • Partially Update an Analysis Group
        • Refresh an Analysis Group
        • Delete an Analysis Group
        • Get Feature Importance for an Analysis Group
    • Demand Surge
      • Get Demand Surges
    • Suggested Radius
      • Get Suggested Radius
    • Saved Locations
      • Create a Saved Location
      • Search Saved Locations
      • Get a Saved Location
      • Search Events for a Saved Location
      • Update a Saved Location
      • Delete a Saved Location
    • Loop
      • Loop Links
        • Create a Loop Link
        • Search Loop Links
        • Get a Loop Link
        • Update a Loop Link
        • Delete a Loop Link
      • Loop Settings
        • Get Loop Settings
        • Update Loop Settings
      • Loop Submissions
        • Search Submitted Events
      • Loop Feedback
        • Search Feedback
    • Places
      • Search Places
      • Get Place Hierarchies
  • WebApp Support
    • WebApp Overview
      • Using the WebApp
      • API Tools
      • Events Search
      • How to Create an API Token
    • Getting Started
      • Can I Give PredictHQ a Go on a Free Trial Basis?
      • How Do I Get in Touch if I Need Help?
      • Using AWS Data Exchange to Access PredictHQ Events Data
      • Using Snowflake to Access PredictHQ Events Data
      • What Happens at the End of My Free Trial?
      • Export Events Data from the WebApp
    • Account Management
      • Managing your Account Settings
      • How Do I Change My Name in My Account?
      • How Do I Change My Password?
      • How Do I Delete My Account?
      • How Do I Invite People Into My Organization?
      • How Do I Log In With My Google or LinkedIn Account?
      • How Do I Update My Email Address?
      • I Signed Up Using My Google/LinkedIn Account, but I Want To Log In With My Own Email
    • API Plans, Pricing & Billing
      • Do I Need To Provide Credit Card Details for the 14-Day Trial?
      • How Do I Cancel My API Subscription?
      • Learn About Our 14-Day Trial
      • What Are the Definitions for "Storing" and "Caching"?
      • What Attribution Do I Have To Give PredictHQ?
      • What Does "Commercial Use" Mean?
      • What Happens If I Go Over My API Plan's Rate Limit?
    • FAQ
      • How Does PredictHQ Support Placekey?
      • Using Power BI and Tableau With PredictHQ Data
      • Can I Download a CSV of Your Data?
      • Can I Suggest a New Event Category?
      • Does PredictHQ Have Historical Event Data?
      • Is There a PredictHQ Mobile App?
      • What Are Labels?
      • What Countries Do You Have School Holidays For?
      • What Do The Different Event Ranks Mean?
      • What Does Event Visibility Window Mean?
      • What Is the Difference Between an Observed Holiday and an Observance?
    • Tools
      • Is PHQ Attendance Available for All Categories?
      • See Event Trends in the WebApp
      • What is Event Trends?
      • Live TV Events
        • What is Live TV Events?
        • Can You Access Live TV Events via the WebApp?
        • How Do I Integrate Live TV Events into Forecasting Models?
      • Labels
        • What Does the Closed-Doors Label Mean?
    • Beam (Relevancy Engine)
      • An Overview of Beam - Relevancy Engine
      • Creating an Analysis in Beam
      • Uploading Your Demand Data to Beam
      • Viewing the List of Analysis in Beam
      • Viewing the Table of Results in Beam
      • Viewing the Category Importance Information in Beam
      • Feature Importance With Beam - Find the ML Features to Use in Your Forecasts
      • Beam Value Quantification
      • Exporting Correlation Data With Beam
      • Getting More Details on a Date on the Beam Graph
      • Grouping Analyses in Beam
      • Using the Beam Graph
      • Viewing the Time Series Impact Analysis in Beam
    • Location Insights
      • An Overview of Location Insights
      • How to Set a Default Location
      • How Do I Add a Location?
      • How Do I Edit a Location?
      • How Do I Share Location Insights With My Team?
      • How Do I View Details for One Location?
      • How Do I View My Saved Locations as a List?
      • Search and View Event Impact in Location Insights
      • What Do Each of the Columns Mean?
      • What Is the Difference Between Center Point & Radius and City, State, Country?
Powered by GitBook

PredictHQ

  • Terms of Service
  • Privacy Policy
  • GitHub

© 2025 PredictHQ Ltd

On this page

Was this helpful?

  1. API Reference
  2. Events

Get Event Counts

Get the count of events by category, PHQ Label and more.

PreviousSearch EventsNextBroadcasts

Last updated 19 days ago

Was this helpful?

OpenAPI Spec

The OpenAPI spec for Events API can be .

Examples

curl -X GET "https://api.predicthq.com/v1/events/count/?country=NZ" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/count/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "country": "NZ"
    }
)

print(response.json())
found here

Get Event Counts

get

Get the count of events by category, PHQ Label and more. The Count endpoint supports the same query parameters as the Search Events endpoint.

Authorizations
Query parameters
active.gtestring · date-timeOptional

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

active.gtstring · date-timeOptional

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

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

active.ltestring · date-timeOptional

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

active.ltstring · date-timeOptional

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

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

active.tzstringOptional

Specifies the timezone for the active.* date parameters.

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

Default: UTC

beam.analysis_idstringOptional

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.

beam.group_idstringOptional

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.

brand_unsafe.excludestring · enumOptional

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

Possible values:
cancelled.gtestring · date-timeOptional

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

cancelled.gtstring · date-timeOptional

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

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

cancelled.ltestring · date-timeOptional

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

cancelled.ltstring · date-timeOptional

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

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

cancelled.tzstringOptional

Specifies the timezone for the cancelled.* date parameters.

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

Default: UTC

countrystring[]Optional

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

Example: US

end.gtestring · date-timeOptional

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

end.gtstring · date-timeOptional

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

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

end.ltestring · date-timeOptional

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

end.ltstring · date-timeOptional

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

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

end.tzstringOptional

Specifies the timezone for the end.* date parameters.

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

Default: UTC

end_around.originstring · dateOptionalDeprecated

Fuzzy date search around event end datetime. When using end_around.* params, origin is required.

Can influence relevance.

Example: 2025-02-01

end_around.offsetstringOptionalDeprecated

The number of days from the origin before the score starts to decay (optional).

Example: 5d

Default: 0d

Pattern: ^\d{1,3}d$
end_around.scalestringOptionalDeprecated

Distance from origin +/- offset at which the score will equal the decay value (optional).

Example: 10d

Default: 3d

Pattern: ^\d{1,3}d$
end_around.decaynumber · double · max: 1OptionalDeprecated

Score value at the scale distance (optional).

Example: 0.9

Default: 0.5

entity.idstring[]Optional

A comma-separated list of Entity identifiers.

Example: XABWvihQAj8TnjvF6WNzLW

first_seen.gtestring · date-timeOptional

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

first_seen.gtstring · date-timeOptional

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.

first_seen.ltestring · date-timeOptional

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

first_seen.ltstring · date-timeOptional

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.

first_seen.tzstringOptional

Specifies the timezone for the first_seen.* date parameters.

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

Default: UTC

idstring[]Optional

A comma-separated list of Event identifiers.

Example: z13B3870YOgv

impact.gtestring · date-timeOptional

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

impact.gtstring · date-timeOptional

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.

impact.ltestring · date-timeOptional

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

impact.ltstring · date-timeOptional

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.

impact.tzstringOptional

Specifies the timezone for the impact.* date parameters.

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

Default: UTC

impact.industrystring · enumOptional

Selected industry for the Predicted Impact Patterns.

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

Example: accommodation

Possible values:
local_rank.gteinteger · max: 100Optional

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

local_rank.gtinteger · max: 100Optional

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

Events without a Local Rank will not be returned.

local_rank.lteinteger · max: 100Optional

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

local_rank.ltinteger · max: 100Optional

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

Events without a Local Rank will not be returned.

location_around.originstringOptionalDeprecated

Fuzzy location search around event location. When using location_around.* params, origin is required.

Please note this affects the relevance value and does not restrict search results to the specified latitude/longitude and offset. Read more in the Relevance guide and combine with the within parameter to restrict results to a specified latitude/longitude and radius.

Example: 40.730610,-73.935242

Pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
location_around.offsetstringOptionalDeprecated

The distance before decay is applied (optional).

Distance unit can be one of m, km, ft, mi.

Example: 2mi

Default: 0km

Pattern: ^\d+(m|km|ft|mi)$
location_around.scalestringOptionalDeprecated

Distance from origin + offset at which the score will equal decay value (optional).

Distance unit can be one of m, km, ft, mi.

Example: 4mi

Default: 2km

Pattern: ^\d+(m|km|ft|mi)$
location_around.decaynumber · double · max: 1OptionalDeprecated

Score value at the scale distance (optional).

Example: 0.9

Default: 0.5

location_confidence_score.gteinteger · min: 1 · max: 5Optional

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.

location_confidence_score.gtinteger · min: 1 · max: 5Optional

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

location_confidence_score.lteinteger · min: 1 · max: 5Optional

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

location_confidence_score.ltinteger · min: 1 · max: 5Optional

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

parent.includestring · enumOptional

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

Possible values:
phq_attendance.gteintegerOptional

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

Example: 2000

phq_attendance.gtintegerOptional

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

phq_attendance.lteintegerOptional

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

Example: 10000

phq_attendance.ltintegerOptional

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

phq_labelstring[]Optional

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

phq_label.opstring · enumOptional

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

Default: any

Possible values:
phq_label.excludestring[]Optional

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

phq_label.exclude.opstring · enumOptional

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

Default: any

Possible values:
place.scopestring[]Optional

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

place.exactstring[]Optional

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.

placekeystring[]Optional

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

postponed.gtestring · date-timeOptional

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

postponed.gtstring · date-timeOptional

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

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

postponed.ltestring · date-timeOptional

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

postponed.ltstring · date-timeOptional

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

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

postponed.tzstringOptional

Specifies the timezone for the postponed.* date parameters.

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

Default: UTC

predicted_end.gtestring · date-timeOptional

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

predicted_end.gtstring · date-timeOptional

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

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

predicted_end.ltestring · date-timeOptional

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

predicted_end.ltstring · date-timeOptional

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

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

predicted_end.tzstringOptional

Specifies the timezone for the predicted_end.* date parameters.

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

Default: UTC

predicted_event_spend.gteintegerOptional

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

predicted_event_spend.gtintegerOptional

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

predicted_event_spend.lteintegerOptional

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

Example: 200000

predicted_event_spend.ltintegerOptional

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

predicted_event_spend_industry.<industry>.<suffix>integerOptional

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.

qstringOptional

A full-text search query.

Can influence relevance.

Example: katy perry

rank.gteinteger · max: 100Optional

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

Example: 80

rank.gtinteger · max: 100Optional

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

rank.lteinteger · max: 100Optional

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

Example: 90

rank.ltinteger · max: 100Optional

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

saved_location.location_idstring[]Optional

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

start.gtestring · date-timeOptional

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

start.gtstring · date-timeOptional

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

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

start.ltestring · date-timeOptional

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

start.ltstring · date-timeOptional

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

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

start.tzstringOptional

Specifies the timezone for the start.* date parameters.

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

Default: UTC

start_around.originstring · dateOptionalDeprecated

Fuzzy date search around event start datetime. When using start_around.* params, origin is required.

Can influence relevance.

Example: 2025-02-01

start_around.offsetstringOptionalDeprecated

The number of days from the origin before the score starts to decay (optional).

Example: 5d

Default: 0d

Pattern: ^\d{1,3}d$
start_around.scalestringOptionalDeprecated

Distance from origin +/- offset at which the score will equal the decay value (optional).

Example: 10d

Default: 3d

Pattern: ^\d{1,3}d$
start_around.decaynumber · double · max: 1OptionalDeprecated

Score value at the scale distance (optional).

Example: 0.9

Default: 0.5

start_date_confidence_score.gteinteger · min: 1 · max: 5Optional

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.

start_date_confidence_score.gtinteger · min: 1 · max: 5Optional

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

start_date_confidence_score.lteinteger · min: 1 · max: 5Optional

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

start_date_confidence_score.ltinteger · min: 1 · max: 5Optional

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

updated.gtestring · date-timeOptional

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

updated.gtstring · date-timeOptional

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

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

updated.ltestring · date-timeOptional

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

updated.ltstring · date-timeOptional

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

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

updated.tzstringOptional

Specifies the timezone for the updated.* date parameters.

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

Default: UTC

withinstringOptional

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

Pattern: ^(?:(?:[1-9]\d*(?:\.\d+)?(km|mi))|(?:[1-9]\d*(m|ft)))@-?\d+(?:\.\d+)?,\-?\d+(?:\.\d+)?$
Responses
200
Successful Response
application/json
get
GET /v1/events/count/ HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer $API_KEY
Accept: */*
200

Successful Response

{
  "count": 1,
  "top_rank": null,
  "top_local_rank": null,
  "rank_levels": {
    "1": 1,
    "2": 1,
    "3": 1,
    "4": 1,
    "5": 1
  },
  "local_rank_levels": {
    "1": 1,
    "2": 1,
    "3": 1,
    "4": 1,
    "5": 1
  },
  "categories": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "phq_labels": {
    "ANY_ADDITIONAL_PROPERTY": 1
  }
}
  • GETGet Event Counts
  • OpenAPI Spec
  • Examples