Requests

The PredictHQ API can be accessed from the https://api.predicthq.com endpoint. With the exception of the authentication endpoint, which only accepts data in a form-encoded format, all data exchanges are performed using the JSON format.

URL

https://api.predicthq.com/{api-version}/{resource}/

Where

  • https:// - the API is only available over Secure HTTP.

  • api.predicthq.com - the API's domain.

  • api-version - the API version identifier, e.g. v1

  • resource - the resource endpoint, e.g. account

Please note that all URLs end with a trailing slash (/).

Actions

The following table describes the different HTTP methods supported by the PredictHQ API and what they mean.

VerbDESCRIPTION
HEADQuery HTTP headers.
OPTIONSRetrieve endpoint information.
GETRetrieve resources.
POSTCreate resources. All mandatory fields should be submitted.
PUTUpdate resources. All mandatory fields should be submitted.
PATCHPartially update resources. Similar to PUT, but you only need to submit the fields that need to be updated.
DELETEDelete resources.

Headers

Authentication

All API calls should have an Authorization header with your Access Token. See the Authentication section for details on how to obtain an Access Token.

Content Negotiation

All API calls should specify the format that is expected in the response. At the moment, JSON is the only supported format.

When sending data, API calls should specify the content type that is being uploaded. Refer to the Resources section for supported formats.

Authorization: Bearer $ACCESS_TOKEN

Accept: application/json
Content-Type: application/json

Parameters

Control the filters to customize your results. The following table describes the different parameter types supported by the API. For a list of parameters accepted by each endpoint, refer to the Resources section.

PARAMETER TYPE DESCRIPTION
String A parameter that accepts text as input. Text data should be URL-encoded.
E.g. ?q=search+query
Number A parameter that accepts a numeric value as input.
E.g. ?limit=10
Date Range A parameter that must have a suffix that specifies a date bound.

Possible suffixes:
  • gte - Greater than or equal.
  • gt - Greater than.
  • lte - Less than or equal.
  • lt - Less than.
  • tz - Time zone the dates in the data should be converted to when being compared to the range.
Notes:
  • The accepted format for this parameter is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.
  • gt=2018-01-01 will match items for which the date time field is > 2018-01-01T23:59:59.999999.
  • gte=2018-01-01 will match items for which the date time field is >= 2018-01-01T00:00:00.000000.
  • lt=2018-01-01 will match items for which the date time field is < 2018-01-01T00:00:00.000000.
  • lte=2018-01-01 will match items for which the date time field is <= 2018-01-01T23:59:59.999999.
E.g. ?start.gte=2018-01-01&start.lte=2019-01-01T12:00:00&start.tz=Pacific/Auckland
Numeric Range A parameter that must have a suffix that specifies a numeric bound.

Possible suffixes:
  • gte - Greater than or equal.
  • gt - Greater than.
  • lte - Less than or equal.
  • lt - Less than.
E.g. ?rank.gte=75&rank.lte=100
Area A parameter that describes a circular area in the form {radius}{unit}@{latitude},{longitude}.
Note that results may contain entities for which the geolocation is not within the radius, but apply to a parent scope of the area specified.
E.g. National school holidays when requesting events affecting a local radius.

Possible radius units:
  • m - Meters.
  • km - Kilometers.
  • ft - Feet.
  • mi - Miles.
E.g. ?within=10km@-36.844480,174.768368

When parameters accept multiple values, the API will return the union of the results for each value. String or numeric values should be separated with a comma (,). E.g. ?id=f0f3159f41c5974a7a,23558618eaedfacb8e

curl -X GET https://api.predicthq.com/v1/events/?limit=10&offset=50 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" 

Sorting

Control the ordering of records that are returned using the standard sort query parameter.

Separate the field names with commas (,) and prefix with minus (-) for reverse ordering.

curl -X GET https://api.predicthq.com/v1/events/?sort=country,-start \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"