Learn how to filter and find events relevant to your business using PredictHQ's Events API.
Events such as concerts, expos and public holidays can shift consumer behavior and impact demand. 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 Events API 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 Location Insights to monitor upcoming events around your stores or locations. Setting up a location is quick and easy in Control Center 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 Saved Locations API.
Use Cases
Demand Forecasting, Visualization and Insights, Dynamic Pricing, Inventory Management, Workforce Optimization and Others
Relevant Industries
Accommodation, Consumer Packaged Goods, Grocery and Supermarkets, Leisure, Travel and Tourism, Marketing and Advertising, Parking, Restaurants, Retail, Transportation and Delivery and Others
Getting Started
A valid access token is required for calling PredictHQ’s APIs. Refer to the API Quickstart for guidance on creating an access token and quickly test our APIs with our API Explorer.
Scenario
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.
How-To Guide
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.
Step 1. Define Query Parameters for the Events API
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 Events API, providing guidance on how to use them along with Tom’s choices:
Date Range
Set the date range for the search.
Active: Use the active parameter to include all events that are ongoing in the date range.
Start: To focus on the start dates of events, the date range should be set using the start parameter.
Settings for Tom’s Pizzeria
Tom is interested in events taking place in the month of June 2024. He will configure the search to include active events from June 1st to June 30th, considering the local time zone.
Define the catchment area for the search. Refer to our industry recommendations 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 Suggested Radius API 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 Places API can assist in finding correct place IDs.
Country-wide: If your interest spans an entire country, the easiest way is to use the country parameter and set it to the res
Settings for Tom’s Pizzeria
Tom is keen on monitoring events within close proximity to his pizzeria so he decides to set the search location using the center point and radius approach.
Tom first uses the Suggested Radius API 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.
params={"within":"1.48mi@47.60,-122.33"}
Suggested Radius
Tom is in the Food and Beverage/Restaurants industry and the pizzeria is located in Downtown Seattle at (47.60, -122.33). These are the two parameters for the Suggested Radius API:
Specific Themes: Use the phq_label parameter to focus on particular themes within a category. For example, to find baseball-related events, set phq_label to baseball.
Settings for Tom’s Pizzeria
For a broad initial survey of upcoming events, Tom has chosen to focus on categories that are likely to influence restaurant visits.
Next, Tom plans to use use Demand Analysis in Control Center to help refine these categories further based on actual data-driven insights, tailored to his pizzeria.
Event Impact
Define the event impact for the search.
PHQ Rank: Use the rank parameter to target events based on their predicted impact, 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 recommended industry minimums.
The rank_level parameter divides the PHQ Rank into five equal bands, for simplified categorization. Levels range from 1 to 5, where 1 represents minor impact, such as a community workshop, and 5 represents major impact, like the Olympics.
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, Local Rank helps differentiate the impact of similar-sized events in different locations, such as Aspen, Colorado versus New York City.
The local_rank_level parameter divides Local Rank into five equal bands, for simplified categorization. Levels also range from 1 to 5, with 1 representing minor impact and 5 representing major impact, similar to the PHQ Rank.
To focus his resources efficiently and avoid spending time on smaller, less impactful events, Tom sets a minimum PHQ rank threshold of 30, which is recommended for his industry.
params={"rank.gte":30}
Event State
Track events based on their likelihood of occurring.
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 subject to change as more information becomes available. Events are marked as deleted if they are canceled, postponed, or otherwise removed.
Focusing primarily on active and predicted event states ensures that only events which are relevant and likely to occur are tracked
Settings for Tom’s Pizzeria
Tom is interested in all upcoming events in June 2024 and has decided to include predicted events as well.
params={"state":"active,predicted"}
Query Modifiers
Optimize search results with useful parameters.
Limit: Specify the maximum number of events per page to return, managing the volume of results and focusing on the most relevant events. Use the next field in the API response to navigate to additional results (refer to Handling Paginated API Responses for more details).
Sort: Order the search results according to specific attributes, most commonly event impact such as rank or phq_attendance, to prioritize high impact events.
Settings for Tom’s Pizzeria
Tom is interested in the top 50 upcoming events for June 2024 that could impact his business. He sets the search parameters to not only manage the scope of results but also ensure that the most significant events are returned first.
params={"limit":50,"sort":"rank"}
For detailed information on all query parameters (including those not shown here), please consult Events API.
Step 2. Call Events API
With the query parameters now configured, the next step is to call the Events API. This can be done using our API Explorer or via your preferred tool. Below is an example Tom's request using python:
import requestsbase_url ="https://api.predicthq.com/v1/events"headers ={"Authorization":"Bearer $ACCESS_TOKEN",# Replace $ACCESS_TOKEN with your actual token"Accept":"application/json"}params ={"within":"1.48mi@47.60,-122.33","category":"public-holidays,school-holidays,conferences,concerts,performing-arts","active.gte":"2024-06-01","active.lte":"2024-06-30","rank.gte":30,"limit":50,"sort":"rank","state":"active,predicted"}response = requests.get(base_url, headers=headers, params=params)if response.status_code ==200:print(response.json())else:print(f"Error fetching response: {response.status_code}")
Handling Paginated API Responses
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:
deffetch_all_pages(base_url=base_url,headers=headers,params=params): results = [] next_url = base_url # Start with the base URLwhile next_url: response = requests.get(next_url, headers=headers, params=params) params =None# After the first request, prevent re-sending initial parametersif response.status_code ==200: data = response.json() results.extend(data['results']) next_url = data.get('next')# Update the next_url from the 'next' field in the responseelse:print(f"Failed to fetch data: {response.status_code}, Message: {response.text}")breakreturn resultsall_events =fetch_all_pages()print("Total events fetched:", len(all_events))
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:
Example Response
{"count":388,"overflow":false,"next":"https://api.predicthq.com/v1/events/?active.gte=2024-06-01&active.lte=2024-06-30&category=public-holidays%2Cschool-holidays%2Cconferences%2Cconcerts%2Cperforming-arts&limit=50&offset=50&rank.gte=30&sort=rank&state=active%2Cpredicted&within=1.48mi%4047.60%2C-122.33","previous":null,"results": [ {"relevance":null,"id":"4hFctf3GqQ2MS5qYLW","title":"Itzy","alternate_titles": ["ITZY 2ND WORLD TOUR 'BORN TO BE'","ITZY at WAMU Theater","Itzy (Concert)" ],"description":"","category":"concerts","labels": ["concert","music" ],"rank":62,"local_rank":77,"phq_attendance":4201,"entities": [ {"entity_id":"hckgG3yNMg5PRGsL49pNzK","name":"ITZY","type":"organization" }, {"entity_id":"3AedBWTgigZjWx9NhwLsvgU","name":"CenturyLink Field - WaMu Theater","type":"venue","formatted_address":"800 Occidental Avenue South\nSeattle, WA 98134\nUnited States of America" } ],"duration":0,"start":"2024-06-07T03:00:00Z","start_local":"2024-06-06T20:00:00","end":"2024-06-07T03:00:00Z","end_local":"2024-06-06T20:00:00","predicted_end":"2024-06-07T07:10:00Z","predicted_end_local":"2024-06-07T00:10:00","updated":"2024-05-15T18:25:53Z","first_seen":"2024-01-26T02:32:24Z","timezone":"America/Los_Angeles","location": [-122.3322862,47.5933082 ],"geo": {"geometry": {"coordinates": [-122.3322862,47.5933082 ],"type":"Point" },"placekey":"zzw-223@5x4-4vs-mp9" },"impact_patterns": [ {"vertical":"accommodation","impact_type":"phq_attendance","impacts": [ {"date_local":"2024-06-05","value":841,"position":"leading" }, {"date_local":"2024-06-06","value":4201,"position":"event_day" }, {"date_local":"2024-06-07","value":421,"position":"lagging" } ] }, {"vertical":"hospitality","impact_type":"phq_attendance","impacts": [ {"date_local":"2024-06-04","value":85,"position":"leading" }, {"date_local":"2024-06-05","value":1051,"position":"leading" }, {"date_local":"2024-06-06","value":4201,"position":"event_day" }, {"date_local":"2024-06-07","value":127,"position":"lagging" } ] } ],"scope":"locality","country":"US","place_hierarchies": [ ["6295630","6255149","6252001","5815135","5799783","7174408","5809844" ] ],"state":"active","private":false,"predicted_event_spend":325046,"predicted_event_spend_industries": {"accommodation":77435,"hospitality":188904,"transportation":58707 },"phq_labels": [ {"label":"pop","weight":0.53 }, {"label":"other","weight":0.47 } ] }, {// More results... } ]}
Key Response Fields
Pagination
Results are returned in a paginated format, where the number of events per page is determined by your subscription limits. The key fields related to pagination include:
count: The total number of events that match the search criteria.
next and previous: URLs that can be used to navigate to the next or previous pages of results, respectively.
overflow: If true, this indicates more results are available but cannot be reached through normal pagination due to subscription limits. Consider making your search query more specific to reduce the number of results returned.
For more comprehensive guidelines on navigating paginated results, refer to Pagination.
Events
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 Response Fields. Common response fields include:
Dates
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 predicted end date fills this gap with predicted_end_local.
start, end, predicted_end: Indicates the start, end and predicted end dates in UTC.
Location
geo: Includes the latitude/longitude coordinates of the event as well as additional location information which is especially useful for events that cover an area rather than a point, such as parades.
place_hierarchies: Lists the place IDs associated with the event location.
country: Identifies the country where the event takes place.
Event Descriptors
title: The name of the event.
description: A brief description of what the event entails, if available.
category: The type of event, such as concerts or public holidays.
phq_labels: Tags that classify the event into common themes or topics. Note, labels is a legacy field and is no longer maintained.
Event Impact
rank: The predicted impact of the event based on a globally comparable rank index.
local_rank: The predicted impact of the event, taking into account the local area.
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.
Relevant Events: Tom aims to pinpoint event categories that impact his business the most by using Demand Analysis in Control Center. 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 Power BI’s AutoML feature with PredictHQ’s event data. This will help him better predict customer flows and optimize resource planning.
Conclusion
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.
