HTTP Request Parameters

Data endpoints support the sending of the returned data to your webhook URL instead of in the response.

To receive the data in the response instead of to your webhook URL, 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:

{
  "message": "Data sent to webhook",
  "reference": String,
  "status": "success",
  "user": TerraUser
}

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 your HTTP request.

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.


Provider-specific Endpoints

Some data providers do not provide data for corresponding endpoints. In this case we return a generic response which adheres to the following schema:

{
  "status": "Data type requested not available from provider",
  "user": TerraUser
}

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:

{
  "status": "Request is processing, try again later",
  "retry_after": Number,
  "user": TerraUser
}

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.


Large Request Chunking

HTTP requests for data over a period longer than 31 days will always be process asynchronously 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:

{
  "user": TerraUser,
  "reference": "UUID",
  "message": "Large request submitted. The data is being processed and will be sent to your webhook in chunks"
}

Before the first segment arrives at your webhook you will receive the following payload:

{
    "reference": "UUID",
    "status": "processing",
    "message": "Large request is processing",
}

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:

{
  "reference": "UUID", 
  "status": "completed", 
  "message": "Large request has been completed"
}