How to Find Cancelled Events with the PredictHQ API
Creating intelligent events data is the heart of what we do. This can be challenging as events are dynamic. Even well established, long running events can be disrupted by the effects of external factors, such as severe weather or the impact of pandemics such as Covid-19 (coronavirus).
From golf tournaments in China, the Geneva Motor Show in Switzerland, the Arnold Sports Festival in the USA; to the world’s biggest international literary event in London – any event can change. Businesses need an intelligent source of event data to get real insights and take action in this rapidly changing situation.
Our feature-rich API allows you to quickly and accurately find events that matter to your business. Whether you need to narrow your search to specific locations of cities, focus on specific types of events using any of our 19 event categories; a specific time range; target only high impact events using our event ranks or restrict the results to those events which have been cancelled – it can all be done quickly and easily via the API.
How to find cancelled events using the PredictHQ API
To find cancelled events using the API you can use our deleted_reason parameter. This blog is for technical audiences such as developers or data scientists. In the example below we will look for cancelled events in the United States.
curl -X GET https://api.predicthq.com/v1/events/?deleted_reason=cancelled&active.gte=2020-02-01&active.lte=2020-03-28&sort=rank&country=US&category=sports,expos,conferences \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
In the examples below you need to use the appropriate access token for your account.
Find out how to make this call in Python see the code samples in our technical docs. In the example above we use the following parameters on our call to the events API:
deleted_reason=cancelled– as mentioned above this tells the API to only return cancelled events.active.gte=2020-02-01&active.lte=2020-03-28– this tells the API to give us events that were active between the 1st of February and the 28th of Marchsort=rank– this tells the API to sort by PHQ Rank™ descending. So that returns the highest impact events first.category=sports,expos,conferences– this limits our search to only these 3 types of events.country=US– that tells the API just to return events in the United States.
This will then get back a list of cancelled events. Below is an extract showing only the first event returned (this is the Arnold Sports Festival):
"id": "rEKiP455mVMBuowHQd",
"deleted_reason": "cancelled",
"title": "Arnold Sports Festival",
"description": "The IFBB Arnold Sports Festival, also known as the Arnold Schwarzenegger Sports Festival, is an annual multi-sport event consisting of professional bodybuilding, strongman, fitness, figure and bikini weekend expo. It was established in 1989 and is named after Arnold Schwarzenegger.",
"category": "sports",
"labels": [
"expo",
"health",
"sport"
],
"rank": 96,
"local_rank": 100,
"aviation_rank": null,
"entities": [
{
"name": "Greater Columbus Convention Center",
"type": "venue",
"formatted_address": "400 North High Street\nColumbus, OH 43215\nUnited States of America",
"entity_id": "JENftd9zp9xZ95yYm9dPHk"
}
],
"duration": 36000,
"start": "2020-03-07T17:00:00Z",
"end": "2020-03-08T03:00:00Z",
"updated": "2020-03-04T02:28:32Z",
"first_seen": "2020-03-04T02:28:19Z",
"timezone": "America/New_York",
"location": [
-83.000813,
39.970315
],
"scope": "locality",
"country": "US",
"place_hierarchies": [
[
"6295630",
"6255149",
"6252001",
"5165418",
"4512214",
"4509177"
]
],
"state": "deleted",
"private": false
}
Or another example if you want to look for cancelled events in the United Kingdom in early March we simply change the country parameter specified in the previous API Request to GB:
curl -X GET https://api.predicthq.com/v1/events/?deleted_reason=cancelled&active.gte=2020-03-08&active.lte=2020-03-10&sort=rank&category=sports,expos,conferences&country=GB \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
One of the first events returned by this is the The London Book Fair, which is an example of a major event that has been cancelled. Looking at a small extract of the information that is returned for that specific event:
"rank": 78,
"local_rank": 85,
"aviation_rank": 80,
We can see the large values for PHQRank™, LocalRank and AviationRank™ indicate the impact this event has on airlines, and at a local and country wide scale.
You can use this with your internal system to find and take action on cancelled events. For example, you may wish to take advantage of a cancelled event and create special offers in your booking system or to forewarn your call center team that an event has been cancelled.
We also have an API endpoint that allows you to look at the combined aggregated impact of multiple events happening on a given day – that’s our Aggregate Event Impact endpoint (see Retrieve Aggregate Event Impact in our technical docs).
This endpoint allows customers to aggregate event impact for a location over a given time period. This makes it simple for businesses seeking to correlate their demand with verified event data.
Once you have achieved correlation, you can use Aggregate Event Impact to predict future impact on your business. In addition to this, you can use the Aggregate Event Impact endpoint to find cancelled events, which may have a detrimental impact on your business. Below we will show how you can return cancelled events with the Aggregate Event Impact endpoint.
Imagine being able to graph your demand against aggregate event impact and being able to see what’s been canceled – in terms of people? Understand not only where to place resources but also how to redirect them in times of need. You can use Aggregate Event Impact to do just that.
To use Aggregate Event Impact:
Begin by identifying your location. We will use the United States in our example.
Next, identify the timeframe you want to investigate – whether that’s a day, week, month or more.
Choose which rank you want to use to calculate the impact value – PHQ Rank™ or Aviation Rank™.
Finally, call our Aggregate Event Impact endpoint to deliver you the values for event impact in that area and timeframe.
Remember you can use our data exporter to export a list of events around a location and look at their impact on your business.
Below is an example of calling the Aggregate Event Impact endpoint for cancelled events in the United States from the 10th of February to the 28th of February:
curl -X GET https://api.predicthq.com/v1/events/impact/?impact_rank=rank&deleted_reason=cancelled&active.gte=2020-02-10&active.lte=2020-02-28&country=US
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
You will notice the parameters are the same as the Events API except that you need to use the impact_rank parameter (which is required) to specify what we use to calculate the event impact, either PHQ Rank™ or Aviation Rank™ . In this example we used PHQ Rank™ .
If you want to visualize the Aggregate Event Impact data you can graph the results yourself, or use the Impact feature in Control Center – the below shows cancelled events in the United States over February and March, in Control Center.
You can use Aggregate Event Impact to look for correlation between your business demand data and events data. See our correlation guide for data scientists if you want to learn more. You can also use Aggregate Event Impact for demand forecasting – Data Scientists can add features to their model to incorporate the output of the API to model the impact on events.
