Last updated
Was this helpful?
Last updated
Was this helpful?
Data can be provided as NDJSON, CSV or Parquet. This document describes the NDJSON data structure.
id
The unique identifier of the event.
parent_event
title
The title of the event.
description
The description of the event.
category
The category of the event.
labels
rank
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.
local_rank
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
.
aviation_rank
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.
phq_attendance
A numerical value that reflects the predicted attendance for supported attendance-based categories. Supported categories include concerts, performing arts, sports, expos, conferences, community, and festivals. Some academic and school holiday events may also include a phq_attendance value to indicate student numbers.
For multi-day events, phq_attendance represents total attendance across the entire duration, except for certain categories like conferences, where it reflects daily attendance.
entities
duration
The difference in seconds between the event start
and the event end
.
start
The date and time the event starts, recorded in UTC. If the timezone is not considered relevant (e.g., Independence Day), the time is stored in UTC to represent the same relative time across all timezones, and the timezone
field will be null.
Additionally, if an event has a start time of midnight in its local timezone, this may indicate that the actual time is unknown. You may wish to omit the time when displaying such events
end
The date and time the event ends, recorded in UTC. If the timezone is not considered relevant (e.g., Independence Day), the time is stored in UTC to represent the same relative time across all timezones, and the timezone
field will be null.
updated
The date and time the event was last updated in UTC.
first_seen
The date and time the event was first seen by PredictHQ in UTC. Also called first_seen
in the Events API.
timezone
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.
geo
impact_patterns
scope
The geographical scope the events apply to. Possible values are:
locality
localadmin
county
region
country
placekey
country
The country code in ISO 3166-1 alpha 2 format. This value is typically present, but in some cases such as events occurring outside any country (e.g. an earthquake in the middle of the ocean), it may be empty.
place_hierarchies
An array of place hierarchies for the event. Each hierarchy is an array of place ids. 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. An empty array is possible and valid.
state
The publication state of the event.
Possible values:
active
- The event is an active event.
postponed
- The event is a postponed event, and is expected to occur at a later date.
cancelled
- The event is a cancelled event and is not expected to occur at a later date.
brand_safe
Whether or not this event is considered brand-safe. Examples of brand-unsafe events include content that promotes hate, violence, or discrimination, coarse language, content that is sexually suggestive or explicit, etc.
cancelled
The date and time the event was marked as cancelled, presented in the UTC timezone. This field will be null if state
is not set to "cancelled" or if the cancellation date is unavailable.
postponed
The date and time the event was marked as postponed, presented in the UTC timezone. This field will be null if state
is not set to "postponed" or if the postponement date is unavailable. Note that this field does not represent the new date and time of the postponed event.
predicted_event_spend
predicted_event_spend_industries
phq_labels
predicted_end
The date and time PredictHQ predicts the event will end, recorded in UTC. If the timezone
field is null, the time represents the same relative time across all timezones. This value is present where an actual timezone
is unknown.
alternate_ids
All alternate IDs for the event. Any event IDs that may have been used for this event in the past will be included here. It does not include the current event ID.
start_local
The date and time when the event begins, expressed in the event's local time zone.
end_local
The date and time when the event ends, expressed in the event's local time zone.
predicted_end_local
The date and time when the event is predicted to end, expressed in the event's local time zone.
region
The region in which the event will be occurring. This field can be null
if the event covers more than a single region.
locality
The locality in which the event will be occurring. A locality is most commonly referred to as a city or town. This field can be null
if the event covers more than a single locality.
postcode
The postal code or ZIP code in which the event will be occurring. This field can be null
if the event covers more than a single post code.
formatted_address
A full formatted address which can include street addresses, locality, postcode, region, and country.
change_action
Indicates if the record has been updated, deleted or inserted. Use when processing the data file to keep your database updated.
Possible values:
insert
- new record, not previously seen.
update
- existing record, updated values.
delete
- deleted record, remove from your dataset.
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. This field only shows if a child event has a parent id. It does not indicate if a parent event has child events. For details see our .
The labels associated with the event. The labels
field is representing PredictHQ's legacy labels, and it's suggested to use the phq_labels
field instead where possible.
See also our docs.
See also our .
See also our .
Aviation Rank is no longer actively supported. For more information, see the .
For details see our .
An array of entities linked to the event. This is a complex data type, please see for details.
The geographic details (location) of the event in GeoJSON format.
See for more information on handling geo
data.
Also known as “Predicted 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. It contains details such as the industry vertical the impact pattern applies to, the type of impact shown in the impact pattern, and an array of objects for each day showing the date in the local timezone of the event and the value of the impact_type for that given day. See also our docs.
The Placekey identifier for the physical address where the event takes place. See . This field will be null
if the "What" part or the "Where" part of the Placekey for the event address couldn't be retrieved.
See also the .
predicted
- The event is a predicted event. For details, see our .
The total predicted event spend (USD) across all supported industries: accommodation, hospitality and transportation. This field will be null
if the predicted event spend is not supported for this event.
See also our docs.
A breakdown of predicted event spend (USD) into the three supported industries: accommodation, hospitality, and transportation. This field will be null
if the predicted event spend is not supported for this event.
See also our docs.
The PHQ Labels associated with the event. This field will be null
if there are no PHQ Labels for this event.
See also our docs.