Skip to main content

API Responses

Endpoint response formats are documented in the Technical Reference.

Some parts are explained in more detail below.

Explain​

As documented in the OpenAPI spec, some requests have an explain parameter. If you set this to true, the response will include an explanation field containing a JSON object. We reserve the right to change the contents of the explanation object, which is why it does not have detailed documentation. However, you can expect it to include information about models used to produce the response data.

Base64 encoding​

The JSON number format does not specify any particular floating-point precision, so our data endpoints allow a base64 response option via the outputFormat request parameter.

In this case, variable data is returned as a base64-encoded array of little-endian 32-bit floating-point numbers.

No Data Values​

Sometimes our API may not be able to supply variable data at a particular location and time. For example, there is no valid wind direction when wind speed is zero and no ocean swell on a site that is on land.

For regular JSON responses, missing data is indicated by a non-zero value in each variable's noData array. The corresponding reasons are described in the response's noDataReasons object.

For JSON+base64 responses, missing data is indicated by 32-bit binary patterns inline in each variable's data array. These patterns are described in the response's noDataValues and are guaranteed to be a subset of valid 32-bit floating point NaN representations. To avoid any hypothetical hardware issues, we recommend checking them using a 32-bit integer type.

There are a variety of different reasons:

  • FILL - some or all model data for the requested variable at that particular point and time contains placeholder "fill" values. Often found near boundaries or because of threshold/partition conditions.
  • GAP - no accessible models contain the variable requested at that point and time.
  • LAND - no valid data was available because the location requested in the model decided upon is on land and the variable in question is not available on land.
  • ICE - similar to LAND but for some polar regions where ice cover interferes.
  • INVALID_HIGH/INVALID_LOW - data was found but it was outside the representable range of the requested variable's numeric domain (please report this to us with the exact request and response).
  • ERROR_INTERNAL - something has gone badly wrong (please report this to us with the exact request and response).

Please note that the noDataValues (or noDataReasons) numbers are not fixed and will vary between requests. Some values described may not be present in the response data, but all values present in the response data will be described.