Filtering and Finding Relevant Events
Learn how to filter and find events relevant to your business using PredictHQ's Events API.
Last updated
Was this helpful?
Learn how to filter and find events relevant to your business using PredictHQ's Events API.
Last updated
Was this helpful?
Events such as concerts, expos and public holidays can shift consumer behavior and . Understanding which events are most relevant to a store or location is therefore critical for effective planning and management. By staying ahead of these events, businesses can better prepare for changes in consumer traffic and purchasing patterns, ensuring optimal staffing and inventory levels.
This tutorial will walk through the while exploring an example involving a pizzeria interested in identifying major upcoming events. The goal is to learn how to effectively define query parameters, make API calls and interpret responses.
Alternatively, use to monitor upcoming events around your stores or locations. Setting up a location is quick and easy in where you can get immediate insights for all created locations. This can also be done securely and at scale from your own environment with the .
Demand Forecasting, Visualization and Insights, Dynamic Pricing, Inventory Management, Workforce Optimization and Others
Accommodation, Consumer Packaged Goods, Grocery and Supermarkets, Leisure, Travel and Tourism, Marketing and Advertising, Parking, Restaurants, Retail, Transportation and Delivery and Others
A valid access token is required for calling PredictHQ’s APIs. Refer to the for guidance on creating an access token and quickly test our APIs with our .
Let's take a fictional example: Tom, the owner of Tom’s Pizzeria in Downtown Seattle, Washington, has experienced overwhelming demand on several occasions, resulting in long lines and significant service delays. Suspecting nearby events were the cause of these surges, he sought to better prepare by identifying upcoming major events. To achieve this, Tom is looking into PredictHQ’s Events API to see how he can obtain this information for the next month.
The sections below will guide you through identifying the top 50 upcoming events near Tom’s Pizzeria over the next month. Follow the steps and code snippets to understand how this can be adapted to fit other business scenarios.
The Events API responses come in a paginated format to limit the amount of data sent in a single response. Here's how you can automatically loop through the paginated API responses to collect all available results:
For information on how to search for events using our SDK, please refer to PredictHQ SDKs.
Once the API call is made, the Events API returns a structured JSON response containing detailed information about the events that match the query parameters. Below is an illustrative example of what the first page of this response might look like, demonstrating initial pagination details and a sample event listing:
With a clear view of upcoming events, Tom plans to leverage this information for various analytical and operational improvements at his Pizzeria:
Data Analysis and Reporting: Tom will load event data into Power BI to generate detailed reports and dashboards, following Using Event Data in Power BI for step-by-step instructions.
This tutorial has demonstrated how to effectively use the Events API to filter out noise and identify events that are most relevant to your business. From configuring query parameters to interpreting the responses, you now have the tools to make informed decisions and strategically plan for future opportunities.
Given the volume of events happening all the time, choosing the right query parameters is crucial for identifying relevant events. The next section outlines the most commonly used parameters from the , providing guidance on how to use them along with Tom’s choices:
Define the catchment area for the search. Refer to our for which location type to start with.
Center Point & Radius: Define a circular area around your store or location by specifying latitude/longitude and a radius using the within
parameter. The can assist in identifying an appropriate radius.
City, State, Country: For targeted searches across a predefined area e.g. specific cities, states or countries, use the place
parameter and provide a place ID. The can assist in finding correct place IDs.
Tom first uses the to establish the optimal search radius (see below for code snippet). The Suggested Radius API recommends a 1.48 mi radius based on typical foot traffic and local demographic data for Food and Beverage/Restaurant industries in urban settings.
Relevant Event Categories: To identify that are most relevant to your location, use in the or the . Alternatively, start with our for which categories to start with.
Next, Tom plans to use in the to help refine these categories further based on actual data-driven insights, tailored to his pizzeria.
PHQ Rank: Use the rank
parameter to target events based on their , with values ranging from 0 to 100. This is useful for filtering out smaller events, ensuring focus on those likely to impact demand. Set the minimum rank threshold by setting rank.gte based on our .
Local Rank: To consider the event's impact on the local area, use local_rank
, which also ranges from 0 to 100. By considering factors like population density, helps differentiate the impact of similar-sized events in different locations, such as Aspen, Colorado versus New York City.
PHQ Attendance: For , impact can be directly measured with phq_attendance
which is the .
Event State: Events classified as active
by the state
parameter have confirmed details including start dates and locations, whereas the details of `predicted` events are as more information becomes available. Events are marked as deleted
if they are canceled, postponed, or otherwise removed.
For detailed information on all query parameters (including those not shown here), please consult .
With the query parameters now configured, the next step is to call the Events API. This can be done using our or via your preferred tool. Below is an example Tom's request using python:
Events are detailed in the results section of the response, each represented as a JSON block. The amount of information provided for each event can vary depending on the type of event and other factors. A comprehensive guide that covers each available field can be found in . Common response fields include:
start_local
, end_local
: Indicates the start and end dates of the event in the local time zone. If an end date is not available, it defaults to the start date. For some events where the end date is not available, a fills this gap with predicted_end_local
.
geo
: Includes the latitude/longitude coordinates of the event as well as additional location information which is especially useful for events that cover rather than a point, such as parades.
place_hierarchies
: Lists the associated with the event location.
category
: The , such as concerts or public holidays.
phq_labels
: that classify the event into common themes or topics. Note, labels
is a legacy field and is no longer maintained.
rank
: The of the event based on a globally comparable rank index.
local_rank
: The of the event, taking into account the local area.
phq_attendance
: The number of people the event, for .
impact_patterns
: The of how the event affects various industries on days surrounding the event.
predicted_event_spend
: The of the event on local businesses.
Relevant Events: Tom aims to pinpoint event categories that impact his business the most by using in the . This will help him allocate his resources more effectively.
Forecast Future Orders: Recognizing the benefits of predictive analytics, Tom is considering developing a demand forecasting model using . This will help him better predict customer flows and optimize resource planning.