NAV Navbar
Logo
http+json shell

Introduction

RiverZone exposes its data via an Application Programming Interface (API). This document is the official reference for that functionality.

To play around with a few examples we recommend a REST client called Postman.

Basic concepts

Assumptions

The API is entirely HTTP-based

Methods to retrieve data from the API require a GET request. Methods that submit or change data require a POST. Methods that destroy data require a DELETE. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one. HTTP Response Codes are meaningful.

The API is a RESTful resource

The API attempts to conform to the design principles of Representational State Transfer (REST). More details on REST can be found here. Libraries to build REST-compatible API clients are readily available for several programming languages. A list of REST frameworks is available at the bottom of the above mentioned page.

The format used for structured data exchange is JSON

The API supports the JSON (JavaScript Object Notation) format. Details on how JSON works can be found here and here. Libraries that convert to and from the JSON format are readily available for popular and less popular programming languages. A full index, sorted by language, can be found at the bottom of this page

SSL/TLS is supported and enforced

The API only works with HTTP-within-SSL/TLS (HTTPS). HTTP requests will be accepted but redirected to the HTTPS endpoint. Issuing HTTPS request from the start is highly recommended to avoid passing both the authentication KEY and potentially confidential data in clear text over the web.

Parameters have certain expectations

Some API methods take optional or requisite parameters. Please keep in mind that all query-string parameter values should be converted to UTF-8 and URL encoded.

Authentication

Authentication is performed using an API key provided by RiverZone. The API key must be included in the HTTPS request using one of the following two methods:

Where both are provided the query-string parameter takes precedence.

The API key is a string, more specifically it is a UUID in its canonical form (e.g.: “123e4567-e89b-12d3-a456-426655440000”).

Throttling

Throttling and rate-limiting schemes are applied on a per-key and per-request-type basis to all requests to prevent overloading the system with too many / too fast requests.

HTTP Response Codes and Errors

HTTP Status Codes

The RiverZone API attempts to return appropriate HTTP status codes for every request.

Error Messages

{
  "errorCode": 3000,
  "errorMessage": "Too many requests in a short amount of time. Slow down"
}

When the RiverZone API returns error messages, it does so in JSON format. See examples in the right panel.

Error Codes

Error codes, as found in the body of returned error messages, further define the scope of an error. The following error codes may be returned:

Stations API

List Stations

curl https://api.riverzone.eu/v1/stations?key=AUTH_KEY
GET /v1/stations/ HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.riverzone.eu

The above command returns JSON structured like this:

{
  "elapsedMs": 576,
  "sources": {
    "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7": {
      "id": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
      "name": "ARPA Veneto",
      "licensingTerms": "Data is not validated and is released by the authority under (CC BY 3.0)[https://creativecommons.org/licenses/by/3.0/deed.it]",
      "website": "http://www.arpa.veneto.it/"
    }
  },
  "stations": [
    {
      "id": "e9696f96-b672-4759-a2cd-5ea3d6a43ea5",
      "revision": -1,
      "enabled": true,
      "countryCode": "IT",
      "state": "",
      "source": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
      "refreshMins": 30,
      "riverName": "Adige",
      "stationName": "Verona",
      "latlng": [
        45442592,
        11001519
      ],
      "readings": {
        "cm": [
          { "ts": 1524027600, "v": -172.0 },
          { "ts": 1524029400, "v": -166.0 },
          { "ts": 1524031200, "v": -155.0 },
          { "ts": 1524033000, "v": -155.0 },
          { "ts": 1524034800, "v": -148.0 },
          { "ts": 1524036600, "v": -153.0 },
          { "ts": 1524038400, "v": -149.0 },
          { "ts": 1524040200, "v": -154.0 },
          { "ts": 1524042000, "v": -152.0 },
          { "ts": 1524043800, "v": -158.0 },
          { "ts": 1524045600, "v": -155.0 },
          { "ts": 1524047400, "v": -156.0 }
        ]
      },
      "notes": null
    },
    {
      "id": "24b2ad1b-46fe-4599-ab19-fe741d2dba57",
      "revision": -1,
      "enabled": false,
      "countryCode": "IT",
      "state": "",
      "source": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
      "refreshMins": 30,
      "riverName": "Agno",
      "stationName": "Ponte Brogliano",
      "latlng": [
        45590122,
        11369741
      ],
      "readings": {},
      "notes": null
    },
    {
      "id": "f2409c6e-3002-4995-a083-b24b7d58ec96",
      "revision": -1,
      "enabled": true,
      "countryCode": "IT",
      "state": "",
      "source": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
      "refreshMins": 30,
      "riverName": "Astico",
      "stationName": "Lugo di Vicenza",
      "latlng": [
        45740386,
        11523260
      ],
      "readings": {
        "cm": [
          { "ts": 1524027600, "v": 54.0 },
          { "ts": 1524029400, "v": 54.0 },
          { "ts": 1524031200, "v": 52.0 },
          { "ts": 1524033000, "v": 51.0 },
          { "ts": 1524034800, "v": 50.0 },
          { "ts": 1524036600, "v": 52.0 },
          { "ts": 1524038400, "v": 50.0 },
          { "ts": 1524040200, "v": 48.0 },
          { "ts": 1524042000, "v": 49.0 },
          { "ts": 1524043800, "v": 50.0 },
          { "ts": 1524045600, "v": 52.0 },
          { "ts": 1524047400, "v": 50.0 }
        ]
      },
      "notes": null
    }
  ]
}

List all Gauging Stations together with 6-hours worth of samples (for enabled stations).

THROTTLING

Leaky bucket (size:2, refill: 1 per 2 minutes)

HTTP REQUEST

GET https://api.riverzone.eu/v1/stations

RETURN VALUES

Property Type Description
stations list of Station All stations
sources list of Source Sources/authorities owning the listed stations
elapsedMs int Time required to fulfill the request, in milliseconds

River Sections API

List River Sections

curl https://api.riverzone.eu/v1/stations?key=AUTH_KEY
GET /v1/stations/ HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.riverzone.eu

The above command returns JSON structured like this:

{
  "elapsedMs": 420,
  "sections": [
    {
      "id": "1612ffdd-c505-4d0e-9aa7-0bf7cdc1efe6",
      "revision": 15,
      "lastUpdatedTs": 1524059771,
      "countryCode": "IT",
      "state": "Veneto",
      "riverName": "Adige",
      "sectionName": "Adige da Chievo a Ponte Ferrovia",
      "category": "whitewater",
      "descriptionUrl": "https://www.ckfiumi.net/consulta.phtml/212/785",
      "putInLatLng": [45458852, 10952308],
      "takeOutLatLng": [45424798, 10995763],
      "grade": "I,II",
      "gauge": {
        "id": "e9696f96-b672-4759-a2cd-5ea3d6a43ea5",
        "unit": "m",
        "min": -2.3,
        "med": null,
        "max": -1,
        "lastUpdatedTs": 1524058553,
        "notes": {
          "en": "ATTENTION: Station is downstream after the confluence of 3 different rivers from 3 different valleys. Actual water level in section may vary based on where it rained"
        }
      },
      "gaugeAlt": [],
      "news": {
        "en": "Tree stuck under Ponte Navi, center arch"
      },
      "pois": [
        {
          "type": "parking",
          "latlng": [45458348, 10952518],
          "notes": {
            "en": "put-in parking"
          }
        },
        {
          "type": "parking",
          "latlng": [45425402, 10995885],
          "notes": {
            "en": "take-out parking"
          }
        },
        {
          "type": "danger",
          "latlng": [45427085, 10995443],
          "notes": {
            "en": "Iron rods under 2nd arch from the left. Avoid with low water"
          }
        },
        {
          "type": "info",
          "latlng": [45427214, 10995022],
          "notes": {
            "en": "Nice play spot in high water conditions"
          }
        }
      ],
      "polys": [
        {
          "grade": "I",
          "poly": [
            [46741463, 11205582],
            [46740257, 11204209],
            [46739551, 11202879],
            [46738816, 11201698],
            [46738198, 11201012],
            [46737316, 11200346],
            [46736375, 11199960]
          ]
        },
        {
          "grade": "II",
          "poly": [
            [46736375, 11199960],
            [46735301, 11199853],
            [46733757, 11199896],
            [46732448, 11200604],
            [46730977, 11201591],
            [46729992, 11202514],
            [46729036, 11203672],
            [46728462, 11204080],
            [46728006, 11203973]
          ]
        },
        {
          "grade": "I",
          "poly": [
            [46728006, 11203973],
            [46727418, 11203136],
            [46726903, 11202406],
            [46726389, 11200861],
            [46725690, 11199027],
            [46725432, 11197696]
          ]
        },
      ],
      "lengthMt": 8500,
      "durationMin": 90
    }
  ],
  "licensingTerms": "All section data is owned by riverzone.eu and published under the Creative Commons Attribution Share-Alike (CC BY-SA) license. See https://creativecommons.org/licenses/by-sa/4.0/ for a human readable summary and https://creativecommons.org/licenses/by-sa/4.0/legalcode for the full license"
}

List all River Sections.

THROTTLING

Leaky bucket (size:2, refill: 1 per 10 minutes)

HTTP REQUEST

GET https://api.riverzone.eu/v1/sections

RETURN VALUES

Property Type Description
sections list of Section All River Sections
licensingTerms String Section data licensing terms
elapsedMs int Time required to fulfill the request, in milliseconds

Object Definitions

Station objects

Station Object properties

{
  "id": "4cf132f2-e0bc-4a1b-a167-a4b80056690c",
  "revision": 2,
  "lastUpdatedTs": 1524914164,
  "enabled": true,
  "riverName": "Adige",
  "stationName": "Verona",
  "countryCode": "IT",
  "state": "Veneto",
  "latlng": [45442594, 11001519],
  "source": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
  "sourceLink": "http://www.arpa.veneto.it/temi-ambientali/acqua/datiacqua/dati_idrometeo_stazione.php?id=332&sr=1&idsr=300005836",
  "refreshMins": 30,
  "notes": {
    "it": "Alcune note sull'idrometro...",
    "en": "Some relevant notes about the station..."
  },
  "parserConfigs": "332,300005836",
  "readings": {
    "cm": [
      { "ts": 1524043800, "v": -158.0 },
      { "ts": 1524045600, "v": -155.0 },
      { "ts": 1524047400, "v": -156.0 }
    ],
    "m3s": [
      { "ts": 1524043800, "v": 99.5 },
      { "ts": 1524045600, "v": 97.4 },
      { "ts": 1524047400, "v": 97.9 }
    ]
  }
}
Property Type Description
id UUID Globally Unique Gauging Station ID
revision int Incremented every time details for this station are edited/updated. Set to -1 if change-tracking is not supported
lastUpdatedTs int Updated every time revision is incremented. Unix epoch. Seconds since Jan 01 1970 (UTC). Set to -1 if change-tracking is not supported
enabled boolean true if RiverZone is collecting samples from this station, false otherwise (station is “dormant”)
riverName String Canonical river name
stationName String Gauging station name (as named by the owning source/authority)
countryCode String ISO 3166-1 alpha-2 Country Code
state String State / region / area
latlng LatLng Gauging station location
source UUID Globally Unique source/authority ID
sourceLink String Where available, direct link to the online Source for this Station. Null otherwise
refreshMins int How often new samples are (usually) published by this station
notes map[LanguageCode]String Generic notes about this station, possibly in multiple languages
parserConfigs String A comma-delimited list of settings used by the parser to extract readings for this station.
WARNING: The format and the nature of data contained in this field is different for each source, may be subject to change without notice and is reported here for completeness’ sake only (and because it might help in crafting sourceLink variants)
readings map[StorageUnit] list of TimestampedValue Latest readings grouped by unit and sorted by timestamp (ascending).
Latest, most recent values are the last ones per unit group

Source Object properties

{
  "id": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
  "name": "ARPA Veneto",
  "licensingTerms": "Data is not validated and is released by the authority under (CC BY 3.0)[https://creativecommons.org/licenses/by/3.0/deed.it]",
  "website": "http://www.arpa.veneto.it/"
}
Property Type Description
id UUID Globally Unique Source/Authority ID
name String Source name
licensingTerms String Licensing terms / ToS (Markdown format)
website String Link to website

Section objects

Section Object properties

{
  "id": "1612ffdd-c505-4d0e-9aa7-0bf7cdc1efe6",
  "revision": 15,
  "lastUpdatedTs": 1524059771,
  "countryCode": "IT",
  "state": "Veneto",
  "riverName": "Adige",
  "sectionName": "Adige: Chievo - Ponte Ferrovia",
  "ordinal": 4,
  "category": "whitewater",
  "descriptionUrl": "https://www.ckfiumi.net/consulta.phtml/212/785",
  "putInLatLng": [45458852, 10952308],
  "takeOutLatLng": [45424798, 10995763],
  "grade": "I,II",
  "gauge": {
    "id": "e9696f96-b672-4759-a2cd-5ea3d6a43ea5",
    "unit": "m",
    "min": -2.3,
    "med": null,
    "max": -1,
    "lastUpdatedTs": 1524058553,
    "notes": {
      "en": "ATTENTION: Station is downstream after the confluence of 3 different rivers from 3 different valleys. Actual water level in section may vary based on where it rained"
    }
  },
  "gaugeAlt": [],
  "news": {
    "en": "Tree stuck under Ponte Navi, center arch"
  },
  "pois": [
    {
      "type": "parking",
      "latlng": [45458348, 10952518],
      "notes": {
        "en": "put-in parking"
      }
    },
    {
      "type": "parking",
      "latlng": [45425402, 10995885],
      "notes": {
        "en": "take-out parking"
      }
    },
    {
      "type": "danger",
      "latlng": [45427085, 10995443],
      "notes": {
        "en": "Iron rods under 2nd arch from the left. Avoid with low water"
      }
    },
    {
      "type": "info",
      "latlng": [45427214, 10995022],
      "notes": {
        "en": "Nice play spot in high water conditions"
      }
    }
  ],
  "polys": [
    {
      "grade": "I",
      "poly": [
        [46741463, 11205582],
        [46740257, 11204209],
        [46739551, 11202879],
        [46738816, 11201698],
        [46738198, 11201012],
        [46737316, 11200346],
        [46736375, 11199960]
      ]
    },
    {
      "grade": "II",
      "poly": [
        [46736375, 11199960],
        [46735301, 11199853],
        [46733757, 11199896],
        [46732448, 11200604],
        [46730977, 11201591],
        [46729992, 11202514],
        [46729036, 11203672],
        [46728462, 11204080],
        [46728006, 11203973]
      ]
    },
    {
      "grade": "I",
      "poly": [
        [46728006, 11203973],
        [46727418, 11203136],
        [46726903, 11202406],
        [46726389, 11200861],
        [46725690, 11199027],
        [46725432, 11197696]
      ]
    },
  ],
  "lengthMt": 8500,
  "durationMin": 90
}
Property Type Description
id UUID Globally Unique River Section ID
revision int Incremented every time details for this section are edited/updated. Set to -1 if change-tracking is not supported
lastUpdatedTs int Updated every time revision is incremented. Unix epoch. Seconds since Jan 01 1970 (UTC). Set to -1 if change-tracking is not supported
countryCode String ISO 3166-1 alpha-2 Country Code this section (mostly) flows through
state String State / region / area this section (mostly) flows through
riverName String Canonical river name
sectionName String Canonical river section name
ordinal int Multiple same-river sections will have increasing ordinal values, with the uppermost section having lowest ordinal value.
This value is only helpful to sort same-river sections from top to bottom when displaying them on a list.
The starting value for ordinal is usually, but not necessarily, 0. Increment step is usually, but not necessarily, 1.
category enum One of whitewater, freestyle, slalom, flatwater
descriptionUrl String Link to river section description/guide. Null if a description is not available
putInLatLng LatLng Location of the classic/default/accepted put-in location (where most people put-in). Null if put-in location is missing
takeOutLatLng LatLng Location of the classic/default/accepted take-out location (where most people take-out). Null if take-out location is missing
grade String WW ICF grade(s) for this section.
Formatted like “III, IV (V+)” to indicate that there are grade III and grade IV (sub)sections and at least one spot graded V+. Set to “?” if grade is missing/unknown
gauge GaugeSettings The reference gauge for this section, where available, together with related display settings
gaugeAlt list of GaugeSettings List of alternate relevant gauges
news map[LanguageCode]String News about this section. Usually important stuff, like up-to-date dangers (trees, landslide, newly-opened syphons, etc)
pois list of Poi List of optional Point of Interests about this section (examples are: alternate put-ins/take-outs, parking locations, dangers, restaurants, etc)
polys list of PolyFragment List of polyline fragments making up the path along the river. Each fragment has a grade attached. Empty array if river polyline is not available
lengthMt int Length of section in meters. Set to -1 if length is unknown
durationMin int How much time it usually takes to run the section under medium-water conditions, in minutes. Set to -1 if duration is unknown

GaugeSettings Object properties

{
  "id": "e9696f96-b672-4759-a2cd-5ea3d6a43ea5",
  "unit": "m",
  "min": -2.3,
  "med": null,
  "max": -1,
  "lastUpdatedTs": 1524058553,
  "notes": {
    "en": "ATTENTION: Station is downstream after the confluence of 3 different rivers from 3 different valleys. Actual water level in section may vary based on where it rained",
    "it": "ATTENZIONE: L'idro è dopo la confluenza di 3 torrenti: Stabina, Val Mora e Brembo di Mezzoldo.\nA seconda delle precipitazioni è quindi possibile che l'acqua arrivi in gran parte da un altro torrente e che il Brembo di Mezzoldo sia secco.\nCon un livello minimo di almeno 0.5 è se non altro probabile riuscire a fare almeno uno dei tre torrenti."
  }
}
Property Type Description
id UUID Globally Unique Gauge ID
unit DisplayUnit The unit we want to display data in
min float Low-water mark in units. Null if not available
med float Medium-water mark in units. Null if not available
max float High-water mark, in units. Null if not available
lastUpdatedTs int The last time min/med/max references were validated/updated. Unix epoch. Seconds since Jan 01 1970 (UTC). Set to -1 if references have never been validated or the last validation date is unknown
notes map[LanguageCode]String Notes about this gauge that are relevant for the river section referencing it. Empty map if no notes

Poi Object properties

{
  "type": "putInAlt",
  "latlng": [46741463, 11205582],
  "notes": {
    "en": "Put-in here to run the IV-grade rapid right before the classic put-in"
  },
  "poly": [
    [46720887, 11193480],
    [46720159, 11192868],
    [46719409, 11192772],
    [46718210, 11192804],
    [46717298, 11192911]
  ],
  "polyStyle": "path"
}
Property Type Description
type enum One of:
putIn: classic put-in, may include path to get there
putInAlt: alternative put-in, may include path to get there
takeOut: classic take-out, may include path to get out of there
takeOutAlt: alterantive take-out, may include path to get out of there
takeOutEmergency: alternative, often impractical take-out to be used in case of an emergency, may include path to get out of there
gauge: location of the reference water gauge
gaugeAlt: location of an alternative water gauge
parking: parking location
webcam: link to a webcam
picture: picture of some feature
food: recommended place to eat
info: generic location-based info
weir: weir or other dangerous but otherwise runnable man-made feature
danger: dangerous spot (permanent), scouting recommended
dangerTemp: temporary danger (tree, log, wire, etc)
death: deadly-dangerous, non-runnable spot (deadly weir, huge drop, unavoidable terminal hole, etc)
portage: portage location, may include path
latlng LatLng Poi location
notes map[LanguageCode]String Optional notes about this Poi. Empty map if no notes
poly list of LatLng Optional. Polyline for this Poi (if relevant, like when type is “portage”,“put-in”,take-out"). Empty list if missing/not-relevant
polyStyle enum Optional. One of portage,path,road. Null if missing/not-relevant
lastUpdatedTs int The last time this POI was validated/updated. Unix epoch. Seconds since Jan 01 1970 (UTC)

PolyFragment Object properties

{
  "grade": "III (V+)",
  "poly": [
    [46741463, 11205582],
    [46736375, 11199960],
    [46728462, 11204080],
    [46725035, 11196817],
    [46717298, 11192911],
    [46709552, 11191517],
    [46702010, 11186860],
    [46696214, 11183266]
  ]
}
Property Type Description
grade string WW ICF grade(s) for this fragment.
The idea is that one poly fragment should have one grade, with maybe a “spot” grade like “III” or “III (V+)”. Spots should ideally be listed as Pois.
poly list of LatLng Polyline

Miscellaneous objects

LatLng Object properties

// Coords for the Arena in Verona, Italy
// https://www.google.com/maps/@45.439,10.994428,20z
[45439000, 10994428]

// Coords for St. Paul's Cathedral, London, UK
// https://www.google.com/maps/@51.513753726152,-0.098655,20z
[51513753, -98655]

[lat, lng] where lat and lng are computed as WGS-84 decimal coords * 1_000_000, rounded down to the nearest integer value.

Example #1:

Example #2:

LanguageCode Object properties

// English
"en"
// English (United States)
"en-us"
// English (United Kingdom)
"en-gb"

IETF language tag represented as a string formatted as languageCode[-countryCode].

StorageUnit Object properties

// Level in centimeters
"cm"
// Flow in m3/s
"m3s"

Enumeration of supported storage units represented as a string.

Allowed values are cm for level and m3s for flow.

DisplayUnit Object properties

// Level units
"cm"
"m"
"ft"
// Flow units
"m3s"
"cfs"

Enumeration of supported display units represented as a string.

Allowed values are cm, m, ft for levels and m3s, cfs for flows.

TimestampedValue Object Properties

{
  "ts": 1524043740,
  "v": 12.2
}
Property Type Description
ts int Unix epoch. Seconds since Jan 01 1970 (UTC)
v float value

DateString Object properties

// December 15, 2015
"20151215"

Date represented as a string formatted as yyyyMMdd.

ErrorResponse Object properties

{
  "errorCode": 3000,
  "errorMessage": "Too many requests in a short amount of time. Slow down"
}
Property Type Description
errorCode int One of the error codes listed here
errorMessage String A human-readable message providing additional details about the error

Revision History

Date (Y/M/D) Description
 
2018/08/21 Added a new parserConfig field to Station Object Properties
2018/07/05 Added a new sourceLink field to Station Object Properties
2018/07/05 Clarified role of lastUpdatedTs field in Station Object Properties and Section Object Properties
2018/07/03 Added a new ordinal field to Section Object Properties to help sort multiple same-river sections from uppermost to lowest
2018/07/03 Added takeOutEmergency option to the ‘type’ enum in the Poi Object
2018/06/08 Added webcam and dangerTemp options to the ‘type’ enum in the Poi Object
2018/06/08 Added a new lastUpdatedTs field to Poi Object
2018/04/29 Added putInAlt, takeOutAlt, gaugeAlt options to the ‘type’ enum in the Poi Object
2018/04/28 List Stations response object revision field is now populated. Added lastUpdatedTs field
2018/04/27 Added a new category field to Section Object Properties to indicate what the section is about: whitewater, freestyle, slalom track or flatwater.
2018/04/27 Added explicit CC-BY-SA licensing terms to data provided by List River Sections
2018/04/27 Fixed incorrect and inverted latitude and longitude coordinates in List River Sections and Section Object Properties examples
2018/04/18 Implemented List River Sections
2018/04/18 Breaking changes on the List Stations response object: sources field changed from map to list for consistency reasons
2018/04/18 First public revision (still a WIP)