Overview

Purpose and Scope

The SkyWise Insight API is an interface to WDT’s Weather as a Service® analytics platform, allowing application developers to leverage high quality weather information for applications, and products. The SkyWise Insight API provides access to historical, current, and forecast data for any region of interest, such as an agriculture field, urban area, or utility service area. API response formats can include time-series, summaries, or contours.


Requests

Authentication

Requests must use basic authentication. Sign up for a username and password (also referred to as an application ID and key) at the Skywise Marketplace. Up to five passwords may be in use at any time. This allows old passwords to be disabled without any downtime.

Methods

Requests must use HTTPS and one of the following methods. Details are provided in the endpoint descriptions.

Method Purpose
DELETE delete an existing resource
GET read a existing resource or list of resources
POST create a new resource
PUT update an existing resource (in its entirety)

Parameters

Some requests may have parameters in the URI query string or request body. Details are provided in the endpoint descriptions.

Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., YYYY-MM-DDThh:mm:ssZ). Resource identifiers use UUIDs and are represented as strings in 8-4-4-4-12 format.

Units

The parameter “unit” is valid on many routes. See the table below for valid unit choices on routes. The default choice is in red.

celsius/fahrenheit millimeters/inches kph/mph
growing-degree-days daily-precipitation hourly-wind-speed
heating-degree-days hourly-precipitation  
cooling-degree-days daily-evapotranspiration-short-crop  
daily-high-temperature daily-evapotranspiration-tall-crop  
daily-low-temperature hourly-evapotranspiration-short-crop  
hourly-temperature hourly-evapotranspiration-tall-crop  
hourly-dewpoint    

Headers

Requests must use the following Accept header, unless otherwise specified in the endpoint description. See versioning for further details.

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

CORS

The API supports cross-origin resource sharing, so that browsers can make requests using JavaScript served from any domain.


Responses

Status Codes

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

Status Description
200 OK the request succeeded
201 Created the resource was successfully created (such as a new asset)
400 Bad Request the request body is syntactically invalid
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
429 Too Many Requests the request has been rate-limited (retry later)
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": "invalid_header",
  "message": "The media type in the Accept header is unsupported.",
  "url": "http://docs.api.wdtinc.com/insight-api/en/latest/overview.html#headers"
}

Formats

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

Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., YYYY-MM-DDThh:mm:ssZ). Resource identifiers use UUIDs and are represented as strings in 8-4-4-4-12 format.


Versioning

Version 1 is the current 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.


Data

WDT’s Platform API provides the data underlying the Insight API. Responses list the Platform API product(s) used to create the result. Platform API Products receive regular updates to improve accuracy; this can cause response values to improve over time.

Missing Data

In cases where there are gaps in data coverage, Insight API will return a response with values based on the data that was available to it at the time of the request. This response will still have an HTTP status code of 200, but will also include a list of ‘missingValidTimes’ that indicate where the gaps in data coverage occurred.

{ 'missingValidTimes': ['2017-01-01T06:00:00Z', '2017-01-01T07:00:00Z']
  .
  .
  .
}