Events API

The Events API gives you a read-only interface to PredictHQ's event data. An event represents something happening at a specific date, time and location, which is either scheduled or unscheduled.

Search Events

Use the below parameters to search and filter all events that are available to your account.

Visibility Window

Please note that you will not receive an error when requesting a date range and/or location that is outside of your subscription's broadcast visibility window. Instead, your visibility window will be automatically applied to your results.

Your plan’s visibility window is shown in your plan summary.

Result Limit

Please note the number of results returned will be limited to your subscription's result limit. If more results exist, the overflow field will be set to true to indicate the count number has been capped to your pagination limit.

Your plan’s pagination limits are shown in your plan summary.

Parameters

Parameter Description
active.*
date range		 The date from and/or to the events intersect with. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.
E.g. ?active.gte=2015-01-01&active.lte=2015-03-01
aviation_rank.*
rank range		 Supports gt, gte, lt and lte suffixes.
Please note that use of a suffix is required.
Note when filtering on aviation_rank events that do not have an aviation_rank will not be returned.
E.g. ?aviation_rank.gte=80&aviation_rank.lte=90
aviation_rank_level
number		 A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ Aviation Rank levels.
Possible values:
  • 1 - Minor (rank between 0 and 20).
  • 2 - Moderate (rank between 21 and 40).
  • 3 - Important (rank between 41 and 60).
  • 4 - Significant (rank between 61 and 80).
  • 5 - Major (rank between 81 and 100).
Note when filtering on aviation_rank_level events that do not have an aviation_rank will not be returned.
E.g. ?aviation_rank_level=4,5
brand_unsafe.*
brand-unsafe		 Whether or not to exclude potentially brand-unsafe events. Potentially brand-unsafe events are included by default.
Currently only supports the exclude suffix.
  • exclude: whether or not to exclude potentially brand-unsafe events from results (required, valid options are true or false)
Examples of brand-unsafe events include content that promotes hate, violence or discrimination, coarse language, content that is sexually suggestive or explicit, etc.
Please note that use of a suffix is required.
E.g. ?brand_unsafe.exclude=true
cancelled.*
date range		 The date from and/or to the event was set to cancelled in the system. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.
Note when filtering on cancelled events that are not cancelled will not be returned.
E.g. ?cancelled.gte=2020-03-01&cancelled.lte=2020-03-15
category
string		 A comma-separated list of categories.
Possible values:
  • academic
  • school-holidays
  • public-holidays
  • observances
  • politics
  • conferences
  • expos
  • concerts
  • festivals
  • performing-arts
  • sports
  • community
  • daylight-savings
  • airport-delays
  • severe-weather
  • disasters
  • terror
  • health-warnings
E.g. ?category=school-holidays,public-holidays
Take a look at the Event Categories page for an overview of the different categories.
country
string		 A comma-separated list of country codes.
E.g. ?country=AU,NZ
deleted_reason
string		 A comma-separated list of deleted reasons for the events.
Possible values:
  • cancelled
  • invalid
  • duplicate
  • postponed
E.g. ?deleted_reason=cancelled,duplicate
end.*
date range		 The date from and/or to the event ends. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.
E.g. ?end.gte=2018-12-19&end.lte=2018-12-19
end_around.*
date around		 Fuzzy date search around event end. Supports origin, offset, scale, decay suffixes.
  • origin: The date (required)
  • offset: The number of days from the origin before the score starts to decay (optional, defaults to 0d)
  • scale: Distance from origin +/- offset at which the score will equal the decay value (optional, defaults to 3d)
  • decay: Score value at the scale distance (optional, defaults to 0.5)
Can influence relevance.
E.g. ?end_around.origin=2018-12-19
entity.id
string		 A comma-separated list of entity identifiers.
E.g. ?entity.id=XABWvihQAj8TnjvF6WNzLW
first_seen
date range		 Find events by the time they were seen for the first time.
Supported suffixes are:
  • gt: greater than.
  • gte: greater than or equal to.
  • lt: less than.
  • lte: less than or equal to.
  • tz: time zone of the first_seen times used;
a TZ Database name.Default is UTC.
The format of first_seen times for this parameter is YYYY-MM-DD or YYYY-MM-DDThh:mm:ss
E.g. ?first_seen.gte=2020-11-30
id
string		 A comma-separated list of event identifiers.
E.g. ?id=z13B3870YOgv
label
string		 A comma-separated list of labels. Use the count endpoint to fetch a list of available labels.
Please note that all event labels are lowercase and that the search is case sensitive.
E.g. ?label=holiday,observance
limit
number		 The maximum number of results to return. The default limit is 10.
E.g. ?limit=10
local_rank.*
rank range		 Supports gt, gte, lt and lte suffixes.
Please note that use of a suffix is required.
Note when filtering on local_rank events that do not have a local_rank will not be returned.
E.g. ?local_rank.gte=80&local_rank.lte=90
local_rank_level
number		 A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ local rank levels.
Possible values:
  • 1 - Minor (rank between 0 and 20).
  • 2 - Moderate (rank between 21 and 40).
  • 3 - Important (rank between 41 and 60).
  • 4 - Significant (rank between 61 and 80).
  • 5 - Major (rank between 81 and 100).
Note when filtering on local_rank_level events that do not have a local_rank will not be returned.
E.g. ?local_rank_level=4,5
location_around.*
location around		 Fuzzy location search around event location.
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.
Supports origin, offset, scale, decay suffixes.
  • origin: The location in the form {latitude},{longitude} (required)
  • offset: The distance before decay is applied (optional, defaults to 0km)(Distance unit can be one of m, km, ft, mi)
  • scale: Distance from origin + offset at which the score will equal decay value (optional, defaults to 2km) (Distance unit can be one of m, km, ft, mi)
  • scale: Distance from origin + offset at which the score will equal decay value (optional, defaults to 2km) (Distance unit can be one of m, km, ft, mi)
  • decay: Score value at scale value (optional, defaults to 0.5)
E.g. ?location_around.origin=40.730610,-73.935242
offset
number		 The number of results to skip. The default is 0.
E.g. ?offset=20
parent.* 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.

Currently supports the include suffix.

include: Whether or not to include parent events in the response (required, valid options are true, false or only)
  • true: include parent events (default behaviour)
  • false: exclude parent events - this will return child events only
  • only: only fetch parent events (exclude child events)
Default value: true.

Please note that use of a suffix is required.

E.g. ?parent.include=false
phq_attendance.*
number range		 Supports gt, gte, lt and lte suffixes.
Please note that use of a suffix is required.
E.g. ?phq_attendance.gte=2000&phq_attendance.lte=10000
place.*
place		 A comma-separated list of place ids (see Places) and/or IATA (3 character), ICAO (4 character), and UN/LOCODE (5 character) airport codes where the events occur. Supports scope or exact suffixes. A CSV file of all supported airport codes and their respective place ids is available to download.
When place.scope is used, 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.

When place.exact is used, results will contain events that apply to the specified place only.E.g. Regional school holidays only.

Please note that use of a suffix is required.
E.g.
  • all events that apply to the State of New York: ?place.scope=5128638
  • all events that apply to the place associated with San Francisco Airport: ?place.scope=SFO
placekey
string		 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.

E.g.?placekey=225@63j-rqb-j7q,@627-s8j-z2k
postponed.*
date range		 The date from and/or to the event was set to postponed in the system. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.
Note when filtering on postponed events that are not postponed will not be returned.
E.g. ?postponed.gte=2020-03-01&postponed.lte=2020-03-15
predicted_end.*
date range		 The date from and/or to the event predicted_end. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.
Note when filtering on predicted_end events that do not have a predicted_end will not be returned.
E.g. ?predicted_end.gte=2018-12-19&predicted_end.lte=2018-12-19
q
string		 A full-text search query.
Can influence relevance.
E.g. ?q=katy+perry
rank.*
rank range		 Supports gt, gte, lt and lte suffixes.
Please note that use of a suffix is required.
E.g. ?rank.gte=80&rank.lte=90
rank_level
number		 A comma-separated list of numbers between 1 and 5, corresponding to the PredictHQ rank levels.
Possible values:
  • 1 - Minor (rank between 0 and 20).
  • 2 - Moderate (rank between 21 and 40).
  • 3 - Important (rank between 41 and 60).
  • 4 - Significant (rank between 61 and 80).
  • 5 - Major (rank between 81 and 100).
E.g. ?rank_level=4,5
relevance
string		 A comma-separated list of components to include when calculating the relevance field of an event.The relevance components are multiplied together to produce the overall relevance.
Parameter Components:
These components correspond to search parameters that can influence relevance. If the parameter isn't provided as part of a search its component will be ignored.By default, relevance includes the components of each relevance-influencing parameter in a search.
  • q
  • start_around
  • end_around
  • location_around
Field Components:
These components correspond to event fields that can be included in relevance. They are not included in relevance by default.
  • rank
  • local_rank
  • aviation_rank

E.g. ?relevance=q,rank,location_around
saved_location.location_id
string		 A comma-separated list of saved location identifiers. This filters the events returned to event within the locations specified. See the Saved Locations API for more details on getting location IDs for a location.
E.g. ?saved_location.location_id=sFlb8HlsLa1j-S4UDEMEkQ
sort
string		 A comma-separated list of fields to sort results by. The default is relevance,-start.
Prefix the field name with - for reverse order.
Possible values:
  • id
  • title
  • start
  • end
  • first_seen
  • predicted_end
  • updated
  • rank
  • local_rank
  • aviation_rank
  • phq_attendance
  • category
  • duration
  • country
  • labels
  • relevance
Note when sorting on predicted_end, local_rank or aviation_rank (regardless of sort order), events that do not have a predicted_end, local_rank or aviation_rank will be placed last.
When sorting by relevance the most relevant results are sorted first, regardless of sort order.
E.g. ?sort=country,-start
start.*
date range		 The date from and/or to the event starts. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.
E.g. ?start.gte=2018-12-19&start.lte=2018-12-19
start_around.*
date around		 Fuzzy date search around event start. Supports origin, offset, scale, decay suffixes.
  • origin: The date (required)
  • offset: The number of days from the origin before the score starts to decay (optional, defaults to 0d)
  • scale: Distance from origin +/- offset at which the score will equal the decay value (optional, defaults to 3d)
  • decay: Score value at the scale distance (optional, defaults to 0.5)
Can influence relevance.
E.g. ?start_around.origin=2018-12-19
state
string		 A comma-separated list of states for the events. Supports active, deleted and predicted. By default, returns active events only.

This parameter is useful in conjunction with updated when you cache events and are interested in retrieving a list of all events that have changed since a specific date and time.

E.g. ?state=active,deleted
updated.*
date range		 The date from and/or to the event was last modified. Supports gt, gte, lt, lte and tz suffixes.

The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

Please note that use of a suffix is required.

E.g. ?updated.gte=2018-05-01T09:55:00Z
within
area		 A geo center and radius in the form {radius}{unit}@{latitude},{longitude}, where the radius unit can be one of: meters m, kilometers km, feet ft, miles 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 need to 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 that it can be difficult working out a suitable radius around your location so to make it easier please use our Suggested Radius API.

E.g. National school holidays that apply to the local radius.
E.g. ?within=2.5mi@-36.844480,174.768368 or ?within=2750m@-36.844480,174.768368

Action

raw
GET /v1/events/

Example

curlpythonraw
curl -X GET https://api.predicthq.com/v1/events/?id=5uRg7CqGu7DTtu4Rfk \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
json
{
    "count": 1,
    "overflow": false,
    "next": null,
    "previous": null,
    "results": [
        {
            "relevance": 0.0,
            "id": "5uRg7CqGu7DTtu4Rfk",
            "parent_event": {
                "parent_event_id": "w7dYyrFwTUQGYE6euv"
            },
            "title": "Formula 1 2019 - United States Grand Prix 2019 - Race",
            "description": "The 2019 United States Grand Prix (officially known as the Formula 1 Emirates United States Grand Prix 2019) was a Formula One motor race held on 3 November 2019 at the Circuit of the Americas in Austin, Texas, United States. The race was the 19th round of the 2019 Formula One World Championship (1 - 3 Nov) and marked the 49th running of the United States Grand Prix.",
            "category": "sports",
            "labels": [
                "auto-racing",
                "f1",
                "sport"
            ],
            "rank": 92,
            "local_rank": 100,
            "aviation_rank": 93,
            "phq_attendance": 120000,
            "entities": [
                {
                    "entity_id": "MasUgUJtWz3kQFVgCG6rJU",
                    "name": "Circuit of the Americas",
                    "type": "venue",
                    "formatted_address": "9201 Circuit of the Americas Boulevard\nAustin, TX 78617\nUnited States of America"
                }
            ],
            "duration": 7200,
            "start": "2019-11-03T19:10:00Z",
            "end": "2019-11-03T21:10:00Z",
            "updated": "2022-11-10T19:50:36Z",
            "first_seen": "2019-07-04T22:14:31Z",
            "timezone": "America/Chicago",
            "location": [
                -97.63585109999997,
                30.1345808
            ],
            "geo": {
                "geometry": {
                    "coordinates": [
                        -97.63585109999997,
                        30.1345808
                    ],
                    "type": "Point"
                },
                "placekey": "222-229@8t2-fgc-z2k"
            },
            "scope": "locality",
            "country": "US",
            "place_hierarchies": [
                [
                    "6295630",
                    "6255149",
                    "6252001",
                    "4736286",
                    "4737316",
                    "4689116"
                ],
                [
                    "6295630",
                    "6255149",
                    "6252001",
                    "4736286",
                    "4737316",
                    "4671654"
                ]
            ],
            "state": "active",
            "private": false
        }
    ]
}

Event Fields

Below are the fields returned by the Events endpoint. Please note that these are not the fields used for filtering - please refer to the Search Events section to discover which parameters can be used for filtering events.

JSON Schemas are available for the Events endpoint and for a single event:

Field Description
aviation_rank
number, null
read-only		 A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. Aviation Rank indicates how much an event will impact flight bookings by considering both domestic and international travel. It can be mapped to the predicted increase in demand based on people flying to an event. Therefore, events with higher Aviation Rank are expected to result in more people taking flights than lower Aviation Rank events.

Aviation Rank is calculated for events in the categories concerts, conferences, expos, sports, festivals, performing-arts, observances, public-holidays, and school-holidays.

If aviation_rank is not intended to be available for an event or we couldn't calculate it, this field will be null.
E.g. 85
cancelled
string, null
read-only		 The date the event was set to cancelled in the system in ISO 8601 format.

All dates are in UTC.

This field will only be present for events with deleted_reason set to cancelled, and will have a null value if cancelled date is not available.

E.g. 2018-12-19T10:00:00Z
category
string
read-only		 The category of the event
Possible values:
  • academic
  • school-holidays
  • public-holidays
  • observances
  • politics
  • conferences
  • expos
  • concerts
  • festivals
  • performing-arts
  • sports
  • community
  • daylight-savings
  • airport-delays
  • severe-weather
  • disasters
  • terror
  • health-warnings
E.g. concerts
country
string
read-only		 The country code in ISO 3166-1 alpha-2 format.
Note that the country value will usually be present but in some cases where the event location is not within a country (e.g. an earthquake in the middle of the ocean) it can be empty.

E.g. NZ
deleted_reason
string
read-only		 The reason why the event was deleted.

Note that this field is only present for events with state deleted.

Possible values:
  • cancelled
  • duplicate
  • invalid
  • postponed
E.g. duplicate
description
string
read-only		 A description of the event.
E.g. See Katy Perry in concert [...]
duplicate_of_id
string
read-only		 The id of the active event this event is a duplicate of.

Note that this field is only present for deleted events with deleted_reason set to duplicate.

E.g. z13B3870YOgv
duration
number
read-only		 The duration of the event in seconds.

E.g. 3600
end
string
read-only		 The end date of the event in ISO 8601 format.

All end dates are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the time zone, and will have a null time zone.

E.g. 2018-12-19T10:00:00Z
entities
array
read-only		 An array of entities linked to the event.

Possible types:
  • event-group
  • venue
E.g. [{"entity_id": "328DxFUbRKvaiJJGyT2gReF", "type": "venue", "name": "Spark Arena", "formatted_address": "Mahuhu Crescent\nAuckland 1010\nNew Zealand"}]
first_seen
string, null
read-only		 The date the event first entered our dataset in ISO 8601 format. All dates are in UTC. This value may be missing on some events, and should not be considered an event announcement date.

E.g. 2017-12-19T06:00:00Z
id
string
read-only		 The unique identifier of the event.

E.g. z13B3870YOgv
impact_patterns
object
read-only		 Also known as “Demand impact patterns”. This field shows impact for leading days (days before the event), lagging days (days after an event) and the days the event occurs.

impact_patterns is an array of impact pattern objects. The same event can have different impact patterns for different industry verticals. It contains the following fields:
  • vertical - The industry vertical the impact pattern applies to. The initial release is for the retail industry so this field will show retail. Future releases could apply to other industries like accommodation.
  • impact_type - Indicates the type of impact shown in the impact pattern. The current version supports PHQ rank only (phq_rank). Future versions could show the impact to attendance or other values.
impacts is an array of objects with one entry for each day that contains the following values:
  • date_local - the date in the local timezone of the event.
  • value - the value of the impact_type for that given day. For example, if the impact_type was phq_rank the value would be the PHQ Rank value on the given day.
  • position - can be leading, event_day or lagging. leading are the days before the event occurs, event_day are the days the event occurs and lagging are the days after the event has occurred.
E.g. { "date_local": "2022-01-08", "value": 10, "position": "leading" }, { "date_local": "2022-01-09", "value": 21, "position": "event_day" },…
labels
array
read-only		 The labels associated with the event. Use the count endpoint to fetch a list of available labels.

E.g. ["holiday", "holiday-national"]
local_rank
number, null
read-only		 Similar to PHQ Rank, this is a log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event on its local geographical area.

Local Rank is calculated for events in the categories community, concerts, conferences, expos, sports, festivals, performing-arts.

If local_rank is not intended to be available for an event, this field will be null.
E.g. 72
location
array
read-only		 A 2-tuple representing the geo location of the event. Note that the longitude/latitude coordinates use the GeoJSON order [lon, lat].

E.g. [174.776792, -36.847319]
geo
object
read-only		 An object containing the geographic information about an event. This field will be used in future instead of the location field (the location field will remain in the current version of the API but could be removed in future versions).

Currently, this field has only one subfield: geometry, which represents the geometry associated with the event in the GeoJSON format.

Possible types:
  • Point
  • Polygon
  • MultiPolygon
E.g. {"geometry": {"type: "Point", "coordinates": [174.776792, -36.847319]}}
parent_event
object
read-only		 Used to indicate if this event is part of a larger event. These types of events are called umbrella events in the system. For example, a large multi-day parent umbrella event may have individual child events for sessions on different days. For example the Formula 1 2019 United States Grand Prix has child events for the qualification, 3 practice events, a concert that occurs at the Grand Prix, and the actual race events (there are 12 child events).

See umbrella events for details on this field and details on what umbrella events are.

Note that this field in this release only shows if a child event has a parent id. It does not indicate if a parent event has child events.

E.g. {"parent_event_id": "w7dYyrFwTUQGYE6euv"}
phq_attendance
number
read-only		 A numerical value that reflects the predicted attendance number for supported attendance-based categories. The following categories are supported: concerts, performing arts, sports, expos, conferences, community and festivals.

phq_attendance reflects the entire attendance for multi-day events (the number of people attending across the full duration of the event) except for some categories like conferences where it is the daily attendance.
See Handling multi-day and Umbrella events for more details.

E.g. 2511
place_hierarchies
array
read-only		 An array of place hierarchies for the event. Each hierarchy is an array of place ids (see Places). The final place in a hierarchy is a specific place the event applies to. Each place is a sub-place of the place immediately preceding it in the hierarchy.

For example, a hierarchy might contain the following places in this order: Earth > Europe > United Kingdom > England > Nottingham

Note that the place_hierarchies value can be an empty array in some cases.

E.g. [["6295630", "6255148", "2635167", "6269131", "3333178", "2641170"]]
placekey
string
read-only		 The Placekey (See placekey.io) reflects the location of an event in the format what@where. Placekey is part of the geo field for an event.

Possible formats
  • {address}-{poi}@{where}
  • {address)@{where}
  • @where
E.g. "placekey": "222-229@8t2-fgc-z2k" or "placekey": "@7f7-mcy-ndv"

Note that Placekey applies to our attended event categories. Some events do not contain a Placekey.
postponed
string, null
read-only		 The date the event was set to postponed in the system in ISO 8601 format.
All dates are in UTC.

This field will only be present for events with deleted_reason set to postponed, and will have a null value if postponed date is not available.

E.g. 2018-12-19T10:00:00Z
predicted_end
string
read-only		 The predicted end date of the event in ISO 8601 format.

Predicted end dates are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the time zone, and will have a null time zone.

This field will only be present if an actual end time is not available for an event and we have a predicted end time.

E.g. 2018-12-19T10:00:00Z
rank
number
read-only		 A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event independent of its geographical location.

E.g. 83
relevance
number, null
read-only		 Relative relevance of the event to the event search.
See the relevance parameter for information on how relevance is calculated.
E.g. 2.9654586
scope
string
read-only		 The geographical scope the events apply to.
Possible values:
  • locality
  • localadmin
  • county
  • region
  • country
E.g. locality
start
string
read-only		 The start date of the event in ISO 8601 format.

All start dates are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the time zone, and will have a null time zone.

If an event has a start time of midnight (in the event time zone) this is an indication that the actual time may be unknown. You may wish to omit the time when displaying these events.

E.g. 2018-12-19T06:00:00Z
state
string
read-only		 The publication state of the event.
Possible values:
  • active: the event is published and valid.
  • deleted: the event was removed, either because it was cancelled or is a duplicate.
  • predicted: events that have an unconfirmed start time i.e for which the exact time the event begins is not yet known.
timezone
string, null
read-only		 The time zone of the event in TZ Database format. This is helpful so you know which time zone to convert the dates to (if needed).

If the time zone is null, the start and end date should be regarded as time zone agnostic and already being in local time. Our start and end filters take this into account when specifying a lower and higher bound on dates.

E.g. Pacific/Auckland
title
string
read-only		 The title of the event.

E.g. Katy Perry
updated
string
read-only		 The last modification date of the event in ISO 8601 format. All dates are in UTC.

E.g. 2018-05-01T05:00:00Z

Event Counts

This endpoint accepts the same parameters as the ones described in Search Events and can be used to get aggregated counts of all matching events that are available to your account.

A JSON Schema is available for the Events Count endpoint: events-count-schema.json

Action

raw
GET /v1/events/count/

Example

curlpythonraw
curl -X GET https://api.predicthq.com/v1/events/count/?country=NZ \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
json
{
  "count": 271423,
  "top_rank": 100.0,
  "top_local_rank": 100.0,
  "top_aviation_rank": 100.0,
  "rank_levels": {
    "1": 163349,
    "2": 75098,
    "3": 17178,
    "4": 5873,
    "5": 9925
  },
  "local_rank_levels": {
    "1": 10524,
    "2": 143054,
    "3": 76958,
    "4": 16460,
    "5": 6323
  },
  "aviation_rank_levels": {
    "1": 25952,
    "2": 78,
    "3": 987,
    "4": 767,
    "5": 212
  },
  "categories": {
    "academic": 2300,
    "airport-delays": 16570,
    "community": 27100,
    "concerts": 44056,
    "conferences": 72503,
    "daylight-savings": 26,
    "disasters": 418,
    "expos": 1601,
    "festivals": 47931,
    "health-warnings": 28,
    "observances": 198,
    "performing-arts": 52698,
    "politics": 12,
    "public-holidays": 434,
    "school-holidays": 38,
    "severe-weather": 277,
    "sports": 7519,
    "terror": 14
  },
  "labels": {
    "agriculture": 60,
    "airport": 16570,
    "american-football": 10,
    "animal": 12,
    "architecture": 6,
    "arson": 11,
    "attack": 12,
    "attraction": 8904,
    "auto-racing": 7,
    "automotive": 20,
    "avalanche": 2,
    "baseball": 21,
    "basketball": 271,
    "bicycle": 1,
    "blizzard": 1,
    "bombing": 2,
    "boxing": 10,
    "business": 3364,
    "campus": 575,
    "career": 187,
    "chemical": 3,
    "closed-doors": 4,
    "clothing": 26,
    "club": 200,
    "cold-wave": 1,
    "comedy": 914,
    "comic": 15,
    "community": 4616,
    "concert": 70570,
    "conference": 72510,
    "construction": 71,
    "course": 2,
    "craft": 41,
    "cricket": 1064,
    "cyclone": 1,
    "daylight-savings": 26,
    "delay": 16570,
    "design": 6,
    "digital": 36,
    "disaster": 418,
    "drought": 3,
    "earthquake": 298,
    "education": 64667,
    "election": 7,
    "entertainment": 3253,
    "environment": 6,
    "epidemic": 1,
    "epidemic-hazard": 28,
    "expo": 1602,
    "family": 9484,
    "fashion": 165,
    "festival": 48574,
    "fire": 54,
    "flood": 106,
    "food": 824,
    "fundraiser": 2161,
    "furniture": 4,
    "gaming": 4,
    "health": 9829,
    "health-warning": 28,
    "heat-wave": 2,
    "hockey": 10,
    "holiday": 670,
    "holiday-local": 286,
    "holiday-national": 148,
    "household": 401,
    "ice-hockey": 20,
    "industrial": 93,
    "instrument": 19,
    "jewelry": 2,
    "landslide": 6,
    "lockdown": 4,
    "marathon": 210,
    "marine": 1,
    "medical": 222,
    "mineral": 2,
    "movie": 3431,
    "music": 71698,
    "natural": 2,
    "observance": 198,
    "observance-season": 52,
    "outdoor": 8663,
    "packaging": 9,
    "parliament": 7,
    "performing-arts": 55955,
    "pet": 3,
    "politics": 390,
    "print": 1,
    "product": 41,
    "rain": 13,
    "referendum": 5,
    "religion": 3234,
    "research-development": 1,
    "rugby": 1837,
    "running": 348,
    "school": 39,
    "science": 1019,
    "seminar": 4,
    "skating": 2,
    "snow": 3,
    "soccer": 3870,
    "social": 7557,
    "sport": 8159,
    "storm": 37,
    "technology": 1473,
    "tennis": 4,
    "terror": 14,
    "tornado": 42,
    "training": 1,
    "transportation": 51,
    "travel": 26,
    "tsunami": 10,
    "volcano": 28,
    "volleyball": 1,
    "weather": 277,
    "weather-warning": 6,
    "wedding": 1,
    "wildfire": 35,
    "wind": 9,
    "wrestling": 3
  }
}

Events Calendar

This endpoint accepts the same parameters as the ones described in Search Events and can be used to get a calendar view of all matching events that are available to your account.

Each day in the calendar contains aggregate counts of all active events for that day.

A JSON Schema is available for the Events Calendar endpoint: events-calendar-schema.json

Action

raw
GET /v1/events/calendar/

Example

curlpythonraw
curl -X GET https://api.predicthq.com/v1/events/calendar/?active.gte=2015-12-24&active.lte=2015-12-25&active.tz=Pacific/Auckland&country=NZ \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
json
{
  "count": 63,
  "next": null,
  "previous": null,
  "results": [
    {
      "date": "2015-12-24",
      "count": 38,
      "top_rank": 90,
      "top_local_rank": 49,
      "top_aviation_rank": 83,
      "rank_levels": {
        "1": 13,
        "2": 16,
        "3": 8,
        "4": 0,
        "5": 1
      },
      "local_rank_levels": {
        "1": 0,
        "2": 21,
        "3": 12,
        "4": 0,
        "5": 0
      },
      "aviation_rank_levels": {
        "1": 3,
        "2": 2,
        "3": 4,
        "4": 1,
        "5": 0
      },
      "categories": {
        "concerts": 13,
        "festivals": 11,
        "airport-delays": 6,
        "sports": 4,
        "politics": 1,
        "school-holidays": 1,
        "observances": 1,
        "daylight-savings": 1,
        "performing-arts": 1
      },
      "labels": {
        "concert": 13,
        "music": 13,
        "festival": 11,
        "airport": 6,
        "delay": 6,
        "sport": 4,
        "holiday": 2,
        "outdoor": 2,
        "daylight-savings": 1,
        "family": 1,
        "election": 1,
        "movie": 1,
        "observance": 1,
        "performing-arts": 1,
        "school": 1
      }
    },
    {
      "date": "2015-12-25",
      "count": 22,
      "top_rank": 90,
      "top_local_rank": 63,
      "top_aviation_rank": 81,
      "rank_levels": {
        "1": 9,
        "2": 10,
        "3": 1,
        "4": 1,
        "5": 1
      },
      "local_rank_levels": {
        "1": 0,
        "2": 8,
        "3": 6,
        "4": 1,
        "5": 0
      },
      "aviation_rank_levels": {
        "1": 5,
        "2": 6,
        "3": 2,
        "4": 2,
        "5": 0
      },
      "categories": {
        "festivals": 10,
        "sports": 5,
        "concerts": 3,
        "school-holidays": 1,
        "public-holidays": 1,
        "daylight-savings": 1,
        "conferences": 1
      },
      "labels": {
        "festival": 10,
        "sport": 5,
        "concert": 3,
        "music": 3,
        "holiday": 2,
        "outdoor": 2,
        "conference": 1,
        "daylight-savings": 1,
        "education": 1,
        "holiday-national": 1,
        "religion": 1,
        "school": 1
      }
    }
  ]
}

Aggregate Event Impact

Aggregate Event Impact has been replaced by the Features API

The Aggregate Event Impact API has been deprecated. It has been replaced by the Features API. We will cease support for Aggregate Event Impact in future.

Please contact us if you require assistance with event attendance aggregations.

Features API

Please see Features API for more information.