General Category Information

This section includes documentation that is common to several categories such as data types, entity information and other common content.

See our resources section for our Events API fields for more details on the fields below.


Date & Time Fields

The date and time are in the same field in an ISO 8601 format, e.g. 2019-05-24T18:00:00Z

Start date: The date when the event starts.

End date: The date when the event ends, end date will be as same as start date when it is not available.

Start time: The time when the event starts. The default start time value is 00:00:00 when it’s not available.

End time: The time when the event ends. The default end time value is 23:59:59 when the start time is not available, or is the same as start time when start time is available but end time is not.

Timezone: The time zone is available for events that impact on a specific location, will return null if the event covers multiple time zones.

  • Note: The time zone of the event in TZ Database format, For example, Pacific/Auckland. Datetime is in UTC when time zone is provided, in local time otherwise

Predicted End Time: A feature calculated end time when an end time is not available, currently available for the sports category.

Note: The date and time are in the same field in an ISO 8601 format, for example, 2019-05-24T18:00:00Z


Event Status

There are three event statuses:

Active: If the event happened or will happen as scheduled.

Cancelled: If the event does not happen as it’s originally planned and it’s not likely to happen in the future.

Postponed: If the event gets delayed for another date.

Note the cancelled or postponed events are marked as archived in Control Center or Public API, to view the events, need to specify the status for example, ?deleted_reason=cancelled,postponed


Location (Scope)

A place represents a Geonames Feature, which can be either an Area; an Administrative Feature; or a Populated Place. Place hierarchies list in an order from general to specific for both point event and area event: planet > continent > country > region > county > locality.

The geonames place hierarchy is returned as a list of place ids in the place_hierarchies field for each event (see the places endpoint for more details on looking up place ids).

A scope indicates the geographical impact of an event. There are two scope types:

1. Point Event

  • Event impacts on a specific point.
  • The event should have a detailed address.
  • Latitude and longitude directs to the provided location.
  • The lowest scope level within a scope hierarchy could be neighbourhood / locality / localadmin.

Point Event Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "place_hierarchies": [
        [
            "6295630",
            "6255149",
            "6252001",
            "5815135",
            "5799783",
            "5786882"
        ]
    ]
}

2. Area event

  • Event impacts on an area.
  • The event should not have a specific location, it may just apply to a city / state or even country.
  • Latitude and longitude directs to the centre of that area.
  • The lowest scope level within a scope hierarchy could be county, region, country.

Area Event Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "place_hierarchies": [
        [
          "6295630",
          "6255149",
          "6251999",
          "6141242"
        ]
    ]
}

Entities

Venue

A venue is a physical location where an event happens. It could be an indoor area, e.g. xx hotel - conference room; or an entire building, e.g. xx stadium; or an outdoor area, e.g. xx park.

Venues will be provided along with both latitude and longitude and address to locate the event.

A venue can be found on an event record as an array of entities with the type of venue

Event Group

Stored within the entities section on an event, an event group identifies recurring events across the PredictHQ events dataset. For example, The (Summer) Olympics repeats every four years around summer time, therefore we would have an event group that is attached to all of our Summer Olympics events.

Events that are associated with event groups have the recurring label and also contain an entity with the type of event-group within the event data.


Ranking for Attended Event Categories

PHQ Rank

PHQ Rank is a numeric value on a logarithmic scale between 0 and 100 to represent the impact of the event. The larger the value of the rank, the higher the impact of the event.

  • PHQ Rank is independent of the event’s location.
  • PHQ Rank for non-attended categories and unscheduled categories are further explained under each category.
  • PHQ Rank is comparable between attended events in terms of the event’s size or impact.

Local Rank

Local Rank is a numeric value on a logarithmic scale between 0 and 100 to represent the impact of an event to its local area. Local Rank may vary even though the PHQ Rank of the events are the same. For example, a conference with 1,000 people in attendance (with PHQ Rank 50) has a Local Rank of 43 in Hong Kong where the local population density is around 64,000, while a Local Rank of 65 in Dublin, Ireland where the local population density is around 5,000.

  • Local Rank is comparable between the attended events in terms of the event’s impact to its local area.
  • Local Rank is not available for area events, the field returns null.

Aviation Rank

Aviation Rank is a numeric value on a logarithmic scale between 0 and 100 to represent the size of the potential impact on air travel by considering both domestic and international travel.

  • This rank is calculated by considering several factors such as the event’s season, geo-location, day of week , event type and more.
  • Events with higher Aviation Rank are expected to bring more air travel passengers than events with lower Aviation Rank.
  • Aviation Rank is comparable across attended events in terms of the impact on air travel.
  • It is a PredictHQ industry-customized rank.
  • Events that are unlikely to cause an impact on airline bookings have Aviation Rank of 0.
  • If events are not applicable for Aviation Rank, or do not have the required metadata to reliably calculate, the field returns null. For example, a terror attack, a local night market, etc.

PHQ Attendance

PHQ Attendance represents the number of people expected to attend an event. For example, an event with a PHQ Rank of 50 has around 1,000 attendance.

PHQ Rank, Local Rank, Aviation Rank, and PHQ Attendance use the following table to translate the numeric value to rank level and tier.

Rank Level Rank Tier Rank Value Expected Attendance
1 Minor

0 - 10
11 - 20

~10
~30

2 Moderate

21 - 30
31 - 40

~100
~300

3 Important

41 - 50
51 - 60

~1,000
~3,000

4 Significant

61 - 70
71 - 80

~10,000
~30,000

6 Major

81 - 90
91 - 100

~100,000
~300,000