Events

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.

There are three ways to access events. You can either:

New Data Sources

As PredictHQ evolves and develops, we will continue to provide more event categories as more sources become available.

If you're interested in a category that is not listed here or would like to see a specific data source added, drop us a line.

Properties

Property

Description

id string read-only

The unique identifier of the event.

E.g. z13B3870YOgv

scope string read-only

The geographical scope the events apply to.

Possible values:

  • locality
  • county
  • region
  • country

E.g. locality

title string read-only

The title of the event.

E.g. Katy Perry

description string read-only

A description of the event.

E.g. A world class, indoor, multi-purpose, all weather arena [...]

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. 2014-12-19T06:00:00Z

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. 2014-12-19T06:00:00Z

updated string

read-only

The last modification date of the event in ISO 8601 format. All dates are in UTC.

E.g. 2014-12-19T06:00:00Z

timezone string 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

duration number read-only

The duration of the event in seconds.

E.g. 3600

category string read-only

The category of the event

Possible values:

  • school-holidays
  • public-holidays
  • observances
  • concerts
  • conferences
  • expos
  • festivals
  • performing-arts
  • community
  • sports
  • daylight-savings
  • airport-delays
  • severe-weather
  • disasters
  • terror

E.g. concerts

labels array read-only

The labels associated with the event

Possible values:

  • air-quality
  • airport
  • attack
  • american-football
  • animal
  • ashfall
  • assassination
  • attraction
  • avalanche
  • baseball
  • basketball
  • blizzard
  • bombing
  • business
  • campus
  • civil
  • club
  • cold-wave
  • comedy
  • community
  • concert
  • conference
  • corporate
  • cricket
  • cyclone
  • daylight-savings
  • delay
  • disaster
  • disaster-warning
  • drought
  • dust
  • earthquake
  • education
  • epidemic
  • estimated
  • execution
  • expo
  • family
  • festival
  • fire
  • flood
  • food
  • fundraiser
  • golf
  • health
  • heat-wave
  • hijacking
  • hockey
  • holiday
  • holiday-christian
  • holiday-hebrew
  • holiday-hindu
  • holiday-local
  • holiday-local-common
  • holiday-muslim
  • holiday-national
  • holiday-orthodox
  • holiday-religious
  • hostage-crisis
  • hurricane
  • ironman
  • landslide
  • mass-shooting
  • movie
  • music
  • observance
  • observance-local
  • observance-season
  • observance-united-nations
  • observance-worldwide
  • outdoor
  • performing-arts
  • politics
  • rain
  • religion
  • rugby
  • sales
  • sand
  • school
  • science
  • shooting
  • snow
  • soccer
  • social
  • space
  • sport
  • stabbing
  • storm
  • technology
  • tennis
  • terror
  • tornado
  • triathlon
  • tsunami
  • typhoon
  • volcano
  • volleyball
  • weather
  • weather-warning
  • wind

E.g. ["holiday", "holiday-national"]

country string read-only

The country code in ISO 3166-1 alpha 2 format.

E.g. NZ

rank number read-only

A number between 0 and 100 representing the estimated importance of the event.

E.g. 50

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]

relevance number read-only

Relative relevance of the event when performing a search, fuzzy date or signal query.

E.g. 2.9654586

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.

Retrieve All 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 that is outside of your subscription's visibility window.

However, your visibility window will be automatically applied to your results.

Parameters

Parameter

Description

limit number

The maximum number of results to return. The default limit is 10, and maximum 200.

E.g. ?limit=20

offset number

The number of results to skip. The default is 0.

E.g. ?offset=20

sort string

A comma-separated list of properties to sort results by. The default is relevance,-start.

Prefix the property name with - for reverse order.

Possible values:

  • id
  • title
  • start
  • end
  • updated
  • rank
  • category
  • duration
  • country
  • labels
  • relevance

E.g. ?sort=country,-start

q string

A full-text search query.

E.g. ?q=katy+perry

id string

A comma-separated list of event identifiers.

E.g. ?id=z13B3870YOgv

start date range

The date from and/or to the event starts. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?start.gte=2014-12-19&start.lte=2014-12-19

end date range

The date from and/or to the event ends. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?end.gte=2014-12-19&end.lt=2014-12-19

active

date range

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

E.g. ?active.gte=2015-01-01&active.lt=2015-03-01

updated date range

The date from and/or to the event was last modified. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?updated.gte=2014-12-19

state string

A comma-separated list of states for the events. Supports active and deleted. By default, returns active events only.

This parameter is useful in conjuction 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

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

category string

A comma-separated list of categories.

Possible values:

  • school-holidays
  • public-holidays
  • observances
  • concerts
  • conferences
  • expos
  • festivals
  • community
  • performing-arts
  • sports
  • daylight-savings
  • airport-delays
  • severe-weather
  • disasters
  • terror

E.g. ?category=school-holidays,public-holidays

label string

A comma-separated list of labels.

Possible values:

  • air-quality
  • airport
  • attack
  • american-football
  • animal
  • ashfall
  • assassination
  • attraction
  • avalanche
  • baseball
  • basketball
  • blizzard
  • bombing
  • business
  • campus
  • civil
  • club
  • cold-wave
  • comedy
  • community
  • concert
  • conference
  • corporate
  • cricket
  • cyclone
  • daylight-savings
  • delay
  • disaster
  • disaster-warning
  • drought
  • dust
  • earthquake
  • education
  • epidemic
  • estimated
  • execution
  • expo
  • family
  • festival
  • fire
  • flood
  • food
  • fundraiser
  • golf
  • health
  • heat-wave
  • hijacking
  • hockey
  • holiday
  • holiday-christian
  • holiday-hebrew
  • holiday-hindu
  • holiday-local
  • holiday-local-common
  • holiday-muslim
  • holiday-national
  • holiday-orthodox
  • holiday-religious
  • hostage-crisis
  • hurricane
  • ironman
  • landslide
  • mass-shooting
  • movie
  • music
  • observance
  • observance-local
  • observance-season
  • observance-united-nations
  • observance-worldwide
  • outdoor
  • performing-arts
  • politics
  • rain
  • religion
  • rugby
  • sales
  • sand
  • school
  • science
  • shooting
  • snow
  • soccer
  • social
  • space
  • sport
  • stabbing
  • storm
  • technology
  • tennis
  • terror
  • tornado
  • triathlon
  • tsunami
  • typhoon
  • volcano
  • volleyball
  • weather
  • weather-warning
  • wind

E.g. ?label=holiday,observance

within area

A geo centre and radius in the form {radius}{unit}@{latitude},{longitude}, where the radius unit can be one of: m, km, ft, mi.

Note that results may contain events that apply to a parent scope of the specified area.

E.g. National school holidays that apply to the local radius.

E.g. ?within=10km@-36.844480,174.768368

place place

A comma-separated list of place ids (see Places) and/or IATA, ICAO and UN/LOCODE airport codes where the events occur. Supports scope or exact suffixes.

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.

E.g. ?place.scope=5128638 (all events that apply to the State of New York)

signal signal

The signal to use for event impact explanation (past) or prediction (future).

Supports the following modifiers:

  • id: the ID of the signal to use for predictions (required)
  • analysis_from: start date of the analysis (optional, defaults to the earliest data point, or 2 years back from the analysis_to date, whichever is later)
  • analysis_to: end date of the analysis (optional, defaults to the latest data point, or today, whichever is earlier)
  • analysis_tz: time zone to use for the purpose of the analysis (optional, defaults to UTC)
  • significance: number between 0 and 100 (optional, defaults to 50)
  • metric: metric to use for event relevance (optional, defaults to demand, valid options are: demand, lead and span)
  • explain: date for which you require an explanation (required for past analysis only)

When signal.explain is not provided, active or start can be used to retrieve future predictions of events that we estimate will impact your business.

For details about signals, see our signals endpoint.

E.g.

  • Past explanation: ?signal.id=reg5gzuWf3ug&signal.explain=2014-12-24
  • Future prediction: ?signal.id=reg5gzuWf3ug&active.gte=2016-06-15&active.lte=2016-06-30 (modify dates accordingly)

country string

A comma-separated list of country codes.

E.g. ?country=AU,NZ


Retrieve Events Count

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


Retrieve Events Calendar

This endpoint accepts the same parameters as the ones described in Retrieve All 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.