Design¶
Overview¶
The WeatherOps™ Archive API is an interface to our Weather as a Service® platform designed for geospatial archive data.
Authentication¶
The API uses IP-based authentication.
Prior to using the API, the customer provides WDT with an IP address (or range of IP addresses) from which the API will be invoked. WDT provides the customer with a username and a hashed token. Then, on each API invocation, a lookup occurs using the username and token parameters on the URI, in addition to the inbound IP address provided by the request environment. Access is granted if these parameters match an authorization record stored by WDT for the specific service requested. If not, a 401 Unauthorized error is returned.
Request Format¶
The generalized form of a URI is as follows:
http://base-uri/v2/resourcePath?parameters
Typically, the resourcePath portion of the URI is composed of:
- A resource type corresponding to one of the supported requests (see following sections).
- A geographic location, expressed as a lat/lon pair in ISO 6709 format (+DD.ddd-DDD.ddd), or a geographic region, expressed as two lat/lon pairs in ISO 6709 format joined together (+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd) representing the northeast and southwest corners.
- In certain cases, a date in RFC 3339 format (YYYY-MM-DDThh:mm:ssZ) or POSIX time (a.k.a. “epoch seconds”).
Valid parameters include:
- REQUIRED: An account username (u) and authentication token (t).
- OPTIONAL (where it applies): A date range bounded by a beginning (begin) and ending (end) timestamp, both in RFC 3339 format (YYYY-MM-DDThh:mm:ssZ) or POSIX time (a.k.a. “epoch seconds”). If unspecified, end defaults to now. The default for begin differs by request and is noted in later sections.
See individual request descriptions for example URIs.
Response Format¶
The default response format is either JSON or GeoJSON, depending on the
request type. Where applicable, KML or XML may be requested using the
Accept header or by appending .kml or .xml, respectively, to the end
of resourcePath, prior to the parameters.
The following are valid ways to obtain JSON using cURL:
curl forensic.api.wdtinc.com/v2/resourcePath?parameters
curl -H "Accept: application/json" forensic.api.wdtinc.com/v2/resourcePath?parameters
The following are valid ways to obtain XML using cURL:
curl forensic.api.wdtinc.com/v2/resourcePath.xml?parameters
curl -H "Accept: application/xml" forensic.api.wdtinc.com/v2/resourcePath?parameters
The following are valid ways to obtain KML using cURL:
curl forensic.api.wdtinc.com/v2/resourcePath.kml?parameters
curl -H "Accept: application/vnd.google-earth.kml+xml" forensic.api.wdtinc.com/v2/resourcePath?parameters
Status Codes¶
The result of an API request can be identified by the status code returned.
| Status | Description |
|---|---|
200 OK |
the request succeeded |
400 Bad Request |
one or more request query parameters are invalid |
401 Unauthorized |
Authentication credentials are invalid or missing |
404 Not Found |
the specified resource does not exist (invalid path) |
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) |
Versioning¶
API releases are versioned using major, minor, and (if needed) micro revision numbers, taking the form major.minor or major.minor.micro. These components increment according to the following policy:
- micro - backward-compatible additions or changes to parameters
- minor - backward-compatible additions or changes to resourcePath
- major - backward-incompatible changes to resourcePath or parameters
The major revision appears in the URI to allow for future indication that backward incompatible changes have been made relative to a prior release. Backward-compatible API changes are continuously and transparently released under the existing major revision.