Observation Sets

Observation Sets are a collection of observations for one or more sites. When a user publishes Observation Sets, they can be integrated into other WeatherOps offerings.

Publishing

Observation Sets can be published in batches up to 1 MB in size.

POST /observation-sets

Required Parameters

Name Type Description Accepted Values Example
id string unique identifier unique string ABC123
latitude numeric latitude (degs) -90.00 to 90.00 (deg) 35.18
longitude numeric longitude (degs) -180.00 to 180.00 (deg) -97.44
elevation numeric above sea level numeric value (meters) 342
time ISO 8601 SO 8601 format ISO 8601 string 2016-05-26T19:52:00Z
variables     see variables table temperature

Request Example

In this example, we’ll provide a couple of precipitation and temperature readings across a day and a collection of aggregated metrics for two different sites.

$ curl -n -X POST "https://obs-integration.api.wdtinc.com/observation-sets \
  -H "Accept: application/vnd.wdt+json; version=1" \
  -H "Content-Type: application/json" \
  -d '
{
  "sites": [
    {
      "id": "field-foo",
      "latitude": 35.0,
      "longitude": -97.0,
      "elevation": 1234,
      "observations": [
        {
          "time": "2015-05-01T06:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 1.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 33.2
            }
          ]
        },
        {
          "time": "2015-05-01T18:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 3.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 33.2
            }
          ]
        },
        {
          "time": "2015-05-02T00:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationAmount",
              "unit": "mm",
              "value": 10.0,
              "method": "sum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 33.0,
              "method": "minimum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 37.7,
              "method": "maximum",
              "interval": 86400
            }
          ]
        }
      ]
    },
    {
      "id": "field-bar",
      "latitude": 37.0,
      "longitude": -95.0,
      "elevation": 4321,
      "observations": [
        {
          "time": "2015-05-01T06:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 3.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 34.2
            }
          ]
        },
        {
          "time": "2015-05-01T18:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 0.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 38.2
            }
          ]
        },
        {
          "time": "2015-05-02T00:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationAmount",
              "unit": "mm",
              "value": 4.0,
              "method": "sum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 32.0,
              "method": "minimum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 38.9,
              "method": "maximum",
              "interval": 86400
            }
          ]
        }
      ]
    }
  ],
  "tags": {
    "network": "Davis"
  }
}
'

Here we are reporting instantaneous values for rate of liquid precipitation and temperature. Each site also reports aggregated metrics for the entire day. See the Reference section for a listing of supported variables and unit types. Reported intervals are in seconds.

We also specify some custom metadata with tags that can be referenced later on. Here we’re referencing a simple source of the data. Users can specify up to 20 different custom tags per Observation Set.

Response Example

Upon successful submission of an Observation Set, the response will include an id as a reference and additional data relevant to the set:

{
  "id": "1a5183f8-9777-4db8-8d2e-558b7996bc05",
  "creationTime": "2015-05-01T00:00:00Z",
  "earliestObservationTime": "2015-05-01T06:00:00Z",
  "latestObservationTime": "2015-05-02T00:00:00Z",
  "tags": {
    "network": "Davis"
  }
}

Listing

Users can retrieve a listing of all published Observation Sets.

By default, this will return the latest 100 Observation Sets with a maximum of 1000 items per listing. Users can also specify a start and end to retrieve a list of all Observation Sets containing obs within the given period.

GET /observation-sets

Query String Parameters (Optional)

Name Type Description Accepted Values / Range Example
start IS0 8601 start date/time string Any valid ISO 8601 string. 2016-06-01T00:00:00Z
end IS0 8601 end date/time string Any valid ISO 8601 string. 2016-06-03

Request Example

To request our latest Observation Sets:

$ curl -n -X GET "https://obs-integration.api.wdtinc.com/observation-sets
  -H "Accept: application/vnd.wdt+json; version=1"

Response Example

We’re returned the Observation Set we published in the previous example.

[{
  "id": "1a5183f8-9777-4db8-8d2e-558b7996bc05",
  "creationTime": "2015-05-01T00:00:00Z",
  "earliestObservationTime": "2015-05-01T06:00:00Z",
  "latestObservationTime": "2015-05-02T00:00:00Z",
  "tags": {
    "network": "Davis"
  }
}]

Retrieving

Users can retrieve previously published Observation Sets using its id.

GET /observation-sets/{observation-set-id}

Request Example

Here, we retrieve the Observation Set using our id from the previous example.

$ curl -n -X GET "https://obs-integration.api.wdtinc.com/observation-sets/1a5183f8-9777-4db8-8d2e-558b7996bc05
  -H "Accept: application/vnd.wdt+json; version=1"

Response Example

{
  "sites": [
    {
      "id": "field-foo",
      "latitude": 35.0,
      "longitude": -97.0,
      "elevation": 1234,
      "observations": [
        {
          "time": "2015-05-01T06:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 1.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 33.2
            }
          ]
        },
        {
          "time": "2015-05-01T18:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 3.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 33.2
            }
          ]
        },
        {
          "time": "2015-05-02T00:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationAmount",
              "unit": "mm",
              "value": 10.0,
              "method": "sum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 33.0,
              "method": "minimum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 37.7,
              "method": "maximum",
              "interval": 86400
            }
          ]
        }
      ]
    },
    {
      "id": "field-bar",
      "latitude": 37.0,
      "longitude": -95.0,
      "elevation": 4321,
      "observations": [
        {
          "time": "2015-05-01T06:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 3.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 34.2
            }
          ]
        },
        {
          "time": "2015-05-01T18:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationRate",
              "unit": "mm/h",
              "value": 0.0
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 38.2
            }
          ]
        },
        {
          "time": "2015-05-02T00:00:00Z",
          "variables": [
            {
              "name": "liquidPrecipitationAmount",
              "unit": "mm",
              "value": 4.0,
              "method": "sum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 32.0,
              "method": "minimum",
              "interval": 86400
            },
            {
              "name": "temperature",
              "unit": "celsius",
              "value": 38.9,
              "method": "maximum",
              "interval": 86400
            }
          ]
        }
      ]
    }
  ],
  "tags": {
    "network": "Davis"
  }
}