Overview

Purpose and Scope

The SkyWise™ Data Transfer API provides simple, authenticated access to SkyWise datasets, such as surface analyses and forecasts, in GeoTIFF or NetCDF format.


Conventions

The API design is inspired by Heroku’s Platform API conventions, as documented on Github.


Requests

Authentication

Requests must use basic authentication. Please contact WDT for a username and password (also referred to as an application ID and key).

Methods

All requests use HTTP GET. Details are provided in the endpoint descriptions.

Parameters

Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., YYYY-MM-DDThh:mm:ssZ).

Headers

Requests must use the following Accept header. See versioning for further details.

Accept: application/vnd.wdt+json; version=1

Requests must also include a basic authentication header.

Requests may use an Accept-Encoding header to obtain gzip-encoded JSON:

Accept-Encoding: gzip

Examples

Endpoint descriptions provide cURL examples to facilitate experimentation. Examples use the -n option to fetch credentials from a ~/.netrc file, which should include an entry similar to the following:

machine data-transfer.api.wdtinc.com
  login {username}
  password {password}

Responses

Status Codes

The result of an API request can be identified by the status code returned.

Status Description
200 OK the request succeeded
401 Unauthorized the authentication credentials are invalid, expired, or missing
403 Forbidden the authentication credentials do not provide access to specified resource
404 Not Found the specified resource does not exist
406 Not Acceptable the Accept header is invalid
422 Unprocessable Entity one or more request parameters are invalid
500 Internal Server Error something is wrong on the server (contact support if the issue persists)
503 Service Unavailable the API is unavailable (contact support if the issue persists)

Client error responses (codes 400-499) also have a JSON body that provides details about the cause of the error.

{
  "id": "product_does_not_exist",
  "message": "The specified product does not exist.",
  "url": "http://docs.api.wdtinc.com/data-transfer-api/en/latest/products.html",
}

Formats

All requests return minified JSON. Futher details and examples (pretty-printed for readability) are provided in the endpoint descriptions.

Gzip-encoding of JSON responses is supported and recommended (see headers).

Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., YYYY-MM-DDThh:mm:ssZ).


Versioning

Version 1 is the current and only supported major version of the API.

Every request must specify a supported major API version in the Accept header to avoid a 406 Not Acceptable error response.

Accept: application/vnd.wdt+json; version=1

Minor and micro API versions (such as 1.1 or 1.0.1) should not be used in the Accept header. These may change frequently with backward-compatible URI, parameter, or header changes.

Any future backward-incompatible changes will only occur under a new major version. This might include the addition, removal, reorganization, or renaming of endpoints.