Note that all these endpoints require the X-API-Key header to be set.
All returned JSON payloads adhere to the following return format unless explicitly stated otherwise:
See Data Models for more information about the models that can be returned.
All fields in the returned payload are nullable, apart from user.user_id, user.provider, and data which are guaranteed to be populated with a string, string, and empty or populated array respectively.
Some endpoints support the sending of the returned data to your webhook URL instead of in the response. Whether or not an endpoint supports this feature can be seen in the endpoint description. To tell the server to send the data in the response instead of to the webhook, you should pass an additional query parameter - to_webhook=false - to the request. If this flag is not passed, you will be sent a payload in the response which adheres to the following schema:
The reference field contains a unique identifier which will also be sent in the webhook request header terra-reference and allows you to link the webhook payload back to the request to our server that fetched the data. Note that the order of the response being sent back to you and the data arriving at your webhook is not guaranteed - therefore the data may arrive at the webhook before you have received the response.
An additional query parameter, with_samples is supported to allow the filtering of sample/timeseries data out of the payload returned to you. If set to false, no samples will be returned in the payload we send. This can significantly reduce the amount of data transferred so may be useful to reduce the amount of time that data transfer takes. The default value is true.
Some data providers do not implement appropriate endpoints for the ones seen below. In this case we return a generic "no data returned response" which adheres to the following schema:
In some cases, providers may require extra time to process data for the request. If this happens, a special response will be returned to you indicating that this is the case. In this response, the field retry_after will be included which contains the number of seconds until the request data will be ready. You should remake the same request after retry_after seconds in order to receive the data. The schema for this response can be seen below:
All HTTP endpoints support response compression. Responses can be compressed using either the brotli or gzip compression algorithms. To enable response compression you should send the algorithm(s) that your HTTP client can accept in the Accept-Encoding header - the server will choose an algorithm to use based on this header and return the compressed response with the header Content-Encoding set appropriately for the algorithm that was used.
HTTP requests for data over a period longer than 31 days will always be process asyncronously by the server. If you make a request for a long period of time, it will be split into one week segments by the server and the result of each segment will be forwarded to your webhook URL as the requests complete.
The server will return the following response to your request if it decides that the request is going to be chunked:
Before the first segment arrives at your webhook you will receive the following payload:
The reference field contains an identifier which will be contained within all data payloads sent to your webhook for the period. As the request is being processed, you will receive multiple payloads to your webhook for the data fetched over the given time period. All of these payloads will conform to the standard webhook data format as well as include the reference field to allow you to link them back to the request that caused them.
After all chunks have completed processing, a further message will be sent to your webhook indicating this: