Requests

The PredictHQ API can be accessed from the https://api.predicthq.com URL. All data exchanges are performed using the JSON format.

You can test-drive the PredictHQ API by importing our Postman Collection below. This is a quick and easy way to become more familiar with our API and how it works.

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 (/).

HTTP Methods

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

Verb	DESCRIPTION
HEAD	Query HTTP headers.
OPTIONS	Retrieve endpoint information.
GET	Retrieve resources.
POST	Create resources. All mandatory fields should be submitted.
PUT	Update resources. All mandatory fields should be submitted.
PATCH	Partially update resources. Similar to PUT, but you only need to submit the fields that need to be updated.
DELETE	Delete resources.

HTTP Headers

Authenticating

All API calls should have an Authorization header with your Access Token. See the Authenticating 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

Query String 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

Pagination

Control the result records that are returned using the standard offset and limit query parameters.

If no limit is specified, then a default of 10 applies.

The maximum number of results and pagination limits are specified in your plan. If you require higher limits, contact us to discuss your needs.

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"