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 SkyWise 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"
}
}