The PredictHQ API will respond to successful requests with either a collection of records or a single record. This section describes the standard format for each record type. Refer to the Resources section for a description of the results for each endpoint.


Content Negotiation

The PredictHQ API will always respond with the Content-Type header set to the format requested via the Accept header. Requests for a format not supported by the API will be rejected with the 406 Not Acceptable status code.

Content-Type: application/json


When requesting a collection of records, the JSON object will usually contain the following fields:

Field Description
count The total number of results.
previous A URL to the previous page, or null if this is the first page.
next A URL to the next page, or null if this is the last page.
results An array of records.

Individual API Endpoint documentation will describe specific response formats.

Result Limit

Additionally, the following field will be provided by the Events endpoint if your subscription has a result limit:

Field Description
overflow Boolean flag that indicates if the search has more results than your subscription allows you to view.

  "count": 189,
  "overflow": false,
  "previous": null,
  "next": "",
  "results": [
        // record 1
        // record 2

    // more records



When requesting a single record, it will be returned as a JSON object. Refer to the API Endpoints sections for a description of possible records.

  "id": "f0f3159f41c5974a7a",
  "title": "Katy Perry",
  "description": "A world class, indoor, multi-purpose, all weather arena attracting the cream of world sports and entertainment ...",
  "category": "concerts",
  "start": "2018-12-19T06:00:00Z",
  "end": "2018-12-19T10:00:00Z",
  "predicted_end": "2018-12-19T10:30:00Z",
  "updated": "2018-05-01T05:00:00Z",
  "first_seen": "2017-12-19T06:00:00Z",
  "timezone": "Pacific/Auckland",
  "duration": 0,
  "rank": 72,
  "local_rank": 85,
  "aviation_rank": 23,
  "country": "NZ",
  "location": [