Requests
The PredictHQ API can be accessed from the https://api.predicthq.com
URL. 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 (/
).
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.
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:
?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:
?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:
?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.
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.