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.


Actions

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 properties should be submitted.
PUT Update resources. All mandatory properties should be submitted.
PATCH Partially update resources. Similar to PUT, but you only need to submit the properties that need to be updated.
DELETE Delete 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.


Parameters

Control the filters to customise 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. ?rank=10

Boolean

A parameter that can be either true or false.

Possible values:

  • true, yes, 1 - True.
  • false, no, 0 - False.

E.g. ?lead=yes

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.

E.g. ?date.gte=2016-01-01&date.lt=2017-01-01&date.tz=Pacific/Auckland

Fuzzy Date

A parameter that accepts an exact date, and extra suffixed parameters specifying the fuzziness of the range.

Possible suffixes:

  • offset - The number of days around this date that are considered 100% relevant.
  • scale - The number of days after which relevancy should drop by 50%.

E.g. ?around=2016-01-01&around.offset=3d&around.scale=1d

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. ?location=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=e5c55724e854289204,afbd75dfc7e6372be2

  • Multiple area values should be separated with a plus sign (+).

    E.g. ?within=10km@-36.844480,174.768368+10km@-41.286201,174.775802


Pagination

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

The maximum limit is 10, which is also the default if no limit is specified.

At most 100 results can be retrieved. E.g. ?limit=10&offset=90 will retrieve the last 10 results.

If you require higher rate limit, get in contact with us to discuss your plan.


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.