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