RiverOnline Vattennivåer i Piteälven


Open API

The set of available APIs are built around the concept of a site. A site has a name, a description, a position and a set of resulting data values deriving from the measurements made and what we know of the site (such as distances between floor of the river and the position of the sensors).

The depth of the river is measured by recording the distance from the water surface up to the sensor that is placed a couple of meter above. The placement of the sensor in relation to the river floor is known, hence the water depth can be derived.

Assume HTTPS usage and support is needed in accessing clients. HTTP works today but may be re-directed to HTTPS in the near future.

Methods

There are two methods and both are accessed through GET commands.

GET sites

Access the following url through an HTTPS GET request

https://www.byteport.se/riveronline/api/2017-08/sites/

Returns a JSON-response that list all available sites. Currently there are not filters (GET parameters) to apply, but this may be added in the future. Each entry in the list contain the following fields:

GET site details

First obtain a valid site ID using the GET sites method, then access this service using the ID as reference.

https://www.byteport.se/riveronline/api/2017-08/site/{site.id}/

Returns a JSON-response that contains the public data for the site.

Can return

200 OK and JSON response as per below.
404 Not Found if invalid ID was given.
500 Internal Error if there are problems with the underlying data feed or calculation errors. Any such error is reported to the system administrators of this site.

NOTE 1: It is up to the client application to decide if the values are good enough to use given the timestamps returned. Should a sensor stop working, the latest values will still be accessible through this service. Take note of the timestamps and act accordingly. Each sensor value carries its own timestamp and each can malfunction or be offline individually or all collectively. The service will still return 200 OK even if one or several sensors have not reported lately.

NOTE 2: All timestamps are in UTC timezone. Make proper adjustments before display in whatever timezone you expect to publish in.

NOTE 3: Clients can compare the current distance to danger to the value recorded yesterday and determine if the water is rising or sinking. Just to be clear: If current value is lower than yesterday, the river is rising. (Do not compare against current level. Yesterdays level is not shown but can be derived from all the figures given.)

The format is quite self explanatory, comments added for clarity where needed.

Example

{
   "position":{
      "lat":65.6667903885686,
      "lng":21.0370652675688
   },
   "data":{
"current":{ // Date and time in UTC when the water level measurements were made. "t":"2017-08-22T12:28:00", // Current water depth "depth":2.05, // Distance from sensor to surface of water "sensor_water_distance":5.95, // Distance left to the lever defined as dangerous level "distance_to_danger":5.15 }, "other":{ // Current light value at the place, in Lux "light":{ "t":"2017-08-22T12:28:00", "v":1730.0 }, // Air humidity, in % "air_rh":{ "t":"2017-08-22T12:28:00", "v":56.3 }, // Air temperature, in °C "air_temperature":{ "t":"2017-08-22T12:28:00", "v":14.2 }, // Water temperature, in °C "water_temperature":{ "t":"2017-08-22T12:28:00", "v":12.4 } }, "yesterday":{ // Depth in meters "depth": 2.15 // Distance to danger about 24 hours ago "distance_to_danger":5.13 // Did we have good data to compare against, 24 hours ago? "distance_to_danger_acceptable":true, } }, "name":"Älvsbybron", "description":"Mätningarna inleddes 2017-05-24." }