Filtering and Finding Relevant Events
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 WebApp 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:
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 requests
base_url = "https://api.predicthq.com/v1/events"
headers = {
"Authorization": "Bearer $ACCESS_TOKEN", # Replace $ACCESS_TOKEN with your actual token
"Accept": "application/json"
}
params = {
"within": "[email protected],-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:
def fetch_all_pages(base_url=base_url, headers=headers, params=params):
results = []
next_url = base_url # Start with the base URL
while next_url:
response = requests.get(next_url, headers=headers, params=params)
params = None # After the first request, prevent re-sending initial parameters
if 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 response
else:
print(f"Failed to fetch data: {response.status_code}, Message: {response.text}")
break
return results
all_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.
Step 3. Interpret Response
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:
Key Response Fields
Next Steps
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.
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.
Last updated
Was this helpful?