Overview

Purpose and Scope

The WeatherOps Historical Obs API gives you access to land-based meteorological observations with data sets dating back to more than a century ago.

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 WeatherOps 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 the following method. Details are provided in the endpoint descriptions.

Method Purpose
GET read a existing resource or list of resources

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
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 401-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/historical-obs-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.

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.

Stations

A station represents a location in a data set where observations have been recorded.

Example: “adair” is a county station in the Oklahoma Mesonet located at 41.5/-94.6.

Observations

An observation is a set of measurements for a variety of parameters measured at a station at a moment in time.

Example: Station XYZ reports an observation on 2016-05-01 at 01:00Z with measurements for relative humidity, temperature, precipitation, and wind direction.

Measurements

A measurement is a numerical value associated with a parameter observed at a moment in time.

Example: An observation could include a measurement of 10 millimeters of precipitation.

Parameters

A parameter is a variable that can be measured by a station.

Example: Temperature is a parameter measured in Celsius, Fahrenheit, or Kelvin.
Parameter Unit Description
altimeter millibars The pressure value to which an aircraft altimeter is set so that it will indicate the altitude relative to mean sea level of an aircraft on the ground at the location for which the value was determined.
cloud_cover percent The percentage of the total celestial dome covered by all layers of clouds.
dewpoint celsius The temperature to which a given parcel of air must be cooled at constant pressure and water vapor content in order for saturation to occur.
maximum_temperature_24h celsius The maximum temperature over the past 24 hours before the observation datetime.
minimum_temperature_24h celsius The maximum temperature over the past 24 hours from the observation time.
precipitation_1h millimeters The depth of liquid precipitation that is measured over the past hour from the observation time.
precipitation_24h millimeters The depth of liquid precipitation that is measured over the past 24 hours from the observation time.
sea_level_pressure millibars The air pressure relative to Mean Sea Level (MSL).
snow_1h centimeters The depth of snow measured over the past hour from the observation time.
snow_24h centimeters The depth of snow measured over the past 24 hours from the observation time.
snow_depth centimeters The depth of snow and ice on the ground.
snow_equivalent centimeters The depth of the liquid content of solid precipitation that has accumulated on the ground.
temperature celsius The temperature of the air.
visibility meters The horizontal distance at which an object can be seen and identified.
wind_direction degrees The angle, measured in a clockwise direction, between true north and the direction from which the wind is blowing.
wind_gust meters per second The rate of speed of a wind gust.
wind_speed meters per second The rate of horizontal travel of air past a fixed point.