NAV Navbar
Logo rm
http+json shell

Introduction

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

Getting Started

  1. Read the documentation (please :)

  2. Contact us at info@rivermap.org to get an API key.

  3. To start experimenting with a few examples we recommend a REST client called Postman. Simply tap the button below to import a pre-made collection of examples and the associated environment variables.

Run in Postman

See the chapter about Postman on how to install and setup the collection.

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 Rivermap. 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 Rivermap 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 Rivermap API returns error messages, it does so in JSON format. See example in the right panel (or above if you’re reading this on a small screen).

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:

Versioning and evolution

Rivermap API is constantly evolving. Existing methods are being improved and extended and new functionalities are being added.

Backward-compatible changes are implemented as extensions to existing versions, while backward-incompatible changes are implemented by introducing entirely new versions.

While we are strongly committed to never introduce breaking changes to existing versions, integration code must be flexible enough to handle backward-compatible updates gracefully.

Here is a list of backward-compatible changes together with how integration code is supposed to deal with them.

Introducing a new REST resource

This is never a problem as existing integration code, not knowing about new endpoints, will not use them.

Adding properties to existing response objects

Existing integration code should ignore unmapped fields.

Note: Some JSON libraries, most notably Jackson, by default will throw an error in case an unmapped field is encountered during parsing. It is important that such libraries are configured to ignore (and possibly report) unmapped fields rather than fail.

Adding optional properties to existing request objects

This is never a problem as existing integration code, not knowing about the new fields, will not populate them.

Adding new values to existing enums in request objects

This is never a problem as existing integration code, not knowing about the new values, will not use them.

Adding new values to existing enums in response objects

This is trickier and we try to limit it only to cases where the change can be handled in a backward-compatible way.

An example would be adding a new value to Poi‘s type property. Existing integration code should ignore POIs with an unknown type (it is still recommended to log these events to keep track of them).

Test with Postman

Postman is a handy API client that facilitates testing and experimenting with RESTful endpoints.

Installing Postman

Before you can use the Rivermap API Postman Collection, you must either download the Postman App for Windows, OS X, or Linux or you can use Postman online:

Install the API Collection

We’ve created a Postman Collection that contains the main Rivermap API RESTful endpoints, including some examples. Click the Run in Postman button below to get started.

Run in Postman

Environment Variables

In order to use the above collection you will need to set some environment variables in Postman. After importing it, select Rivermap API Environment from the list of environments and populate the following:

License

Disclaimer

No warranty, expressed or implied, is made regarding the availability, accuracy, adequacy, completeness, legality, reliability or usefulness of the information provided by this API. The information is provided on an 'as is’ basis. All warranties of any kind, express or implied, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, and non-infringement of proprietary rights are disclaimed.

Station Data

Each Station data, including name and location, is owned by its Source.

Each Source has its own license and terms of service. These are outlined in the Source objects returned by List Stations or List Sources.

Visual Station Readings by Rivermap are licensed under a Creative Commons Attribution 4.0 International (CC BY 4.0) License.

CC BY 4.0 Logo

Section Data

All Section data is a derived work by Rivermap, incorporating additional data from:

It is licensed under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License.

CC BY-SA 4.0 Logo

Sources API

List Sources

curl https://api.rivermap.org/v2/sources?key=AUTH_KEY

GET /v2/sources/ HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 46,
  "sources": [
    {
      "id": "0d69435a-7035-46ac-b6d9-568260925f71",
      "name": "Protezione Civile Provincia Autonoma di Bolzano - Ufficio Idrografico",
      "shortName": "Ufficio Idrografico (BZ)",
      "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://weather.provinz.bz.it/",
      "countryCode": "IT"
    },
    {
      "id": "bc5faa96-9ee1-4668-b445-44346603eec9",
      "name": "Provincia Autonoma di Trento, Dipartimento Protezione Civile - Servizio Prevenzione Rischi, Ufficio Dighe",
      "shortName": "Ufficio Dighe (TN)",
      "licensingTerms": "Data is not validated and is released by the authority under Creative Commons Attribution 4.0",
      "website": "http://www.floods.it/public/homepage.php",
      "countryCode": "IT"
    }
  ]
}

List all Data Sources (aka: Authorities, aka: the entities providing Station data).

THROTTLING

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

HTTP REQUEST

GET https://api.rivermap.org/v2/sources

RETURN VALUES

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

Stations API

List Stations

curl https://api.rivermap.org/v2/stations?key=AUTH_KEY

GET /v2/stations/ HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 576,
  "sources": [
    {
      "id": "0d69435a-7035-46ac-b6d9-568260925f71",
      "name": "Protezione Civile Provincia Autonoma di Bolzano - Ufficio Idrografico",
      "shortName": "Ufficio Idrografico (BZ)",
      "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://weather.provinz.bz.it/",
      "countryCode": "IT"
    },
    {
      "id": "bc5faa96-9ee1-4668-b445-44346603eec9",
      "name": "Provincia Autonoma di Trento, Dipartimento Protezione Civile - Servizio Prevenzione Rischi, Ufficio Dighe",
      "shortName": "Ufficio Dighe (TN)",
      "licensingTerms": "Data is not validated and is released by the authority under Creative Commons Attribution 4.0",
      "website": "http://www.floods.it/public/homepage.php",
      "countryCode": "IT"
    }
  ],
  "rivers": [],
  "stations": [
    {
      "id": "aeafd2a1-5ee8-4780-98c0-7cbc5acdf29e",
      "type": "online",
      "revision": 5,
      "revisionTs": 1524914164,
      "isActive": true,
      "sensors": ["level", "flow"],
      "name": "S.Giorgio/St.Georgen",
      "riverId": null,
      "river": {
        "it": "Aurino",
        "de": "Ahr"
      },
      "state": "Alto Adige",
      "countryCode": "IT",
      "dataSourceId": "0d69435a-7035-46ac-b6d9-568260925f71",
      "sourceLinks": {
        "it": {
          "level": "http://meteo.provincia.bz.it/stazioni-idrometriche.asp?stat_stid=127",
          "flow": null
        },
        "en": {
          "level": "http://weather.provinz.bz.it/gauging-stations.asp?stat_stid=127",
          "flow": null
        },
        "de": {
          "level": "http://wetter.provinz.bz.it/pegelstationen.asp?stat_stid=127",
          "flow": null
        }
      },
      "parserConfigs": "127",
      "latlng": [
        46817197,
        11935257
      ],
      "observationFreqMins": 30,
      "publishingFreqMins": 30,
      "note": {
        "it": "Alcune note sull'idrometro...",
        "en": "Some relevant notes about the station..."
      },
      "synthetic": null
    },
    {
      "id": "04d0980c-a251-422a-a2c0-e699c84936fe",
      "type": "online",
      "revision": 5,
      "revisionTs": 1524914164,
      "isActive": true,
      "sensors": ["level"],
      "name": "Malé",
      "riverId": null,
      "river": {
        "it": "Noce"
      },
      "state": "Trentino",
      "countryCode": "IT",
      "dataSourceId": "bc5faa96-9ee1-4668-b445-44346603eec9",
      "sourceLinks": {
        "it": {
          "level": "http://www.floods.it/public/GraficiPub.php?Sensore=11732&Argomento=0",
          "flow": "http://www.floods.it/public/GraficiPub.php?Sensore=18711&Argomento=0"
        }
      },
      "parserConfigs": "11732,18711",
      "latlng": [
        46347113,
        10913822
      ],
      "observationFreqMins": 15,
      "publishingFreqMins": 15,
      "note": {
        "it": "Alcune note sull'idrometro...",
        "en": "Some relevant notes about the station..."
      },
      "synthetic": null
    }
  ],
  "license": "https://api.rivermap.org/doc/v2/#license"
}

List all Gauging Stations.

THROTTLING

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

HTTP REQUEST

GET https://api.rivermap.org/v2/stations[?status=active][&type=online]

QUERYSTRING PARAMETERS

Property Type Description
status enum Optional. If not specified defaults to active. Can be one of:
all: include all stations
active: include only active stations [default]
inactive: include only non-active stations
type enum Optional. If not specified defaults to all. Can be one of:
all: include all stations [default]
online: include only online stations
manual: include only manual stations
synthetic: include only synthetic stations

RETURN VALUES

Property Type Description
stations list of Station All requested stations
rivers list of River NOT YET SUPPORTED
Rivers referenced by the listed stations
sources list of Source Sources/authorities owning the listed stations
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Get All Readings

curl https://api.rivermap.org/v2/stations/readings?key=AUTH_KEY

GET /v2/stations/readings HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 240,
  "readings": {
    "aeafd2a1-5ee8-4780-98c0-7cbc5acdf29e": {
      "cm": [
        { "ts": 1535700000, "v": 134 },
        { "ts": 1535701800, "v": 134 },
        { "ts": 1535702400, "v": 133 },
        { "ts": 1535707800, "v": 125 },
        { "ts": 1535710200, "v": 124 }
      ]
    },
    "04d0980c-a251-422a-a2c0-e699c84936fe": {
      "m3s": [
        { "ts": 1535699700, "v": 11.88 },
        { "ts": 1535700600, "v": 12.29 },
        { "ts": 1535701500, "v": 11.88 },
        { "ts": 1535702400, "v": 11.88 },
        { "ts": 1535703300, "v": 11.88 }
      ],
      "cm": [
        { "ts": 1535699700, "v": 50 },
        { "ts": 1535700600, "v": 51 },
        { "ts": 1535701500, "v": 50 },
        { "ts": 1535702400, "v": 50 },
        { "ts": 1535703300, "v": 50 }
      ]
    }
  },
  "license": "https://api.rivermap.org/doc/v2/#license"
}

Return readings collected by all active Stations in the indicated time range (last 6 hours by default).

Note: only active stations collect readings

THROTTLING

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

HTTP REQUEST

GET https://api.rivermap.org/v2/stations/readings[?from=YYYYMMddHHmm|mm][&to=YYYYMMddHHmm|mm]

QUERYSTRING PARAMETERS

Property Type Description
from DateTime or int Indicates the start (inclusive) of the time range. Can be either an absolute UTC timestamp (e.g: 201808261810) or a relative-to-now number of minutes (e.g.: 60 to indicate “now - 60 minutes”). Defaults to 360.
to DateTime or int Indicates the end (inclusive) of the time range. Can be either an absolute UTC timestamp (e.g: 201808262359) or a relative-to-from number of minutes (e.g.: 60 to indicate “from + 60 minutes”). Defaults to 360.
LIMIT: the maximum duration of any given range is 6 hours

RETURN VALUES

Property Type Description
readings map[UUID]ReadingsRange Maps stationIds to their readings collected in the indicated time range
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Get Station Readings

curl https://api.rivermap.org/v2/stations/04d0980c-a251-422a-a2c0-e699c84936fe/readings?key=AUTH_KEY

GET /v2/stations/04d0980c-a251-422a-a2c0-e699c84936fe/readings HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 105,
  "readings": {
    "m3s": [
      { "ts": 1535699700, "v": 11.88 },
      { "ts": 1535700600, "v": 12.29 },
      { "ts": 1535701500, "v": 11.88 },
      { "ts": 1535702400, "v": 11.88 },
      { "ts": 1535703300, "v": 11.88 }
    ],
    "cm": [
      { "ts": 1535699700, "v": 50 },
      { "ts": 1535700600, "v": 51 },
      { "ts": 1535701500, "v": 50 },
      { "ts": 1535702400, "v": 50 },
      { "ts": 1535703300, "v": 50 }
    ]
  },
  "license": "https://api.rivermap.org/doc/v2/#license"
}

Return readings collected by the specified Station in the indicated time range (last 6 hours by default).

Note: only active stations collect readings

THROTTLING

Leaky bucket (size:20, refill: 1 per second)

HTTP REQUEST

GET https://api.rivermap.org/v2/stations/:stationId/readings[?from=YYYYMMddHHmm|mm][&to=YYYYMMddHHmm|mm]

PATH PARAMETERS

Property Type Description
stationId UUID The Station id

QUERYSTRING PARAMETERS

Property Type Description
from DateTime or int Indicates the start (inclusive) of the time range. Can be either an absolute UTC timestamp (e.g: 201808261810) or a relative-to-now number of minutes (e.g.: 60 to indicate “now - 60 minutes”). Defaults to 360.
to DateTime or int Indicates the end (inclusive) of the time range. Can be either an absolute UTC timestamp (e.g: 201808262359) or a relative-to-from number of minutes (e.g.: 60 to indicate “from + 60 minutes”). Defaults to 360.
LIMIT: the maximum duration of any given range is 6 hours

RETURN VALUES

Property Type Description
readings ReadingsRange readings collected by the given station in the indicated time range
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Submit Reading

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://api.rivermap.org/v2/stations/ed50818d-2dd4-48f4-8f1c-9875849d1e89/readings?key=AUTH_KEY

POST /v2/stations/ed50818d-2dd4-48f4-8f1c-9875849d1e89/readings HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org
Content-Type: application/json

{
  "reading": {
    "cm": { "ts": 1524027600, "v": -172 }
  }
}

The above command returns JSON structured like this:

{
  "license": "https://api.rivermap.org/doc/v2/#license",
  "elapsedMs": 15
}

Submit a reading for a manual gauge.

THROTTLING

Leaky bucket (size:5, refill: 1 per minute)

HTTP REQUEST

POST https://api.rivermap.org/v2/stations/:stationId/readings

PATH PARAMETERS

Property Type Description
stationId UUID The Station id (must be a manual station)

REQUEST BODY

Property Type Description
reading map[StorageUnit]TimestampedValue Level and/or flow readings
Note: readings that would overwrite existing ones are discarded. Requests with timestamps in the future will return an error

RETURN VALUES

Property Type Description
license String Readings data licensing terms (or link to them)
elapsedMs int Time required to fulfill the request, in milliseconds

River Sections API

List River Sections

curl https://api.rivermap.org/v2/stations?key=AUTH_KEY

GET /v2/stations/ HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 420,
  "sections": [
    {
      "id": "5b8a3684-bf0e-4476-b302-bb246183928c",
      "revision": 17,
      "revisionTs": 1535743444,
      "createdTs": 1528712750,
      "riverOrdinal": 1,
      "countryCode": "IT",
      "regionId": "881ce4bd-486e-45e2-8035-7becf23ebbb7",
      "riverId": null,
      "river": {
        "it": "Isarco",
        "de": "Eisack"
      },
      "sectionName": {
        "it": {
          "formattedName": "[Mezzaselva - Fortezza]",
          "qualifier": "",
          "name": "",
          "from": "Mezzaselva",
          "to": "Fortezza",
          "isCanonical": true
        },
        "de":{
          "formattedName": "[Mittewald - Franzensfeste]",
          "qualifier": "",
          "name": "",
          "from": "Mittewald",
          "to": "Franzensfeste",
          "isCanonical": true
        }
      },
      "category": "whitewater",
      "grade": "III-IV",
      "spotGrades": ["V"],
      "lengthMt": 8000,
      "verticalMt": 240,
      "durationMins": 180,
      "calibration": {
        "stationId": "66a85908-2951-469c-b391-8c98b40371de",
        "isIndirect": false,
        "unit": "m3s",
        "lw": 10,
        "mw": 25,
        "mwMin": 15,
        "mwMax": 35,
        "hw": 50,
        "lastReviewedTs": 1535742132,
        "note": {
          "it": "Alcune note sulle calibrazioni",
          "en": "Some relevant notes about calibrations"
        }
      },
      "calibrationsAlt": [
        {
          "stationId": "66a85908-2951-469c-b391-8c98b40371de",
          "isIndirect": false,
          "unit": "cm",
          "lw": null,
          "mw": null,
          "mwMin": null,
          "mwMax": null,
          "hw": null,
          "lastReviewedTs": 1535742132,
          "note": {
            "en": "Same gauging station as the one used by main calibrations but shows the 'level' sensor. Helpful on the many occasions when the 'flow' sensor stops working"
          }
        }
      ],
      "putInLatLng": [46807920, 11571862],
      "takeOutLatLng": [46789068,11612050],
      "riverGuideLinks": {
        "it": "[Descrizione su CKFiumi](https://ckfiumi.net/consulta.phtml/258/267)",
        "en": "A description of the lower section is [here](http://yaddayadda/guides/isarco).\nThe CKFiumi guide (in italian) is probably more complete"
      },
      "poiIds": [
        { "id": "6402c49c-b8ed-4d99-80b6-20c6bf83fc34", "revision": 0 },
        { "id": "bafbe1d8-9ec7-41bf-ae5c-d9760ef05e9a", "revision": 1 },
        { "id": "ef05c260-6e33-4784-bdd6-992eac84f23e", "revision": 0 },
        { "id": "9cb9d345-90b3-4226-9671-11119c667002", "revision": 1 }
      ],
      "closures": [
        {
          "type": "seasonal",
          "reason": {
            "it": "Periodo di accoppiamento del Sarchiapone",
            "en": "Mating period for endangered local species"
          },
          "from": "06-01",
          "to": "09-01"
        }
      ],
      "customFields": {}
    }
  ],
  "rivers": [],
  "regions": [
    {
      "id": "881ce4bd-486e-45e2-8035-7becf23ebbb7",
      "names": {
        "it": "Alto Adige",
        "de": "Südtirol"
      }
    }
  ],
  "pois": [
    {
      "id": "6402c49c-b8ed-4d99-80b6-20c6bf83fc34",
      "revision": 0,
      "revisionTs": 1528711420,
      "createdTs": 1528711420,
      "type": "putIn",
      "latlng": [46807920, 11571862],
      "note": {},
      "label": "",
      "poly": [],
      "polyStyle": null
    },
    {
      "id": "bafbe1d8-9ec7-41bf-ae5c-d9760ef05e9a",
      "revision": 1,
      "revisionTs": 1528712750,
      "createdTs": 1528711420,
      "type": "takeOut",
      "latlng": [46789068,11612050],
      "note": {}
    },
    {
      "id": "ef05c260-6e33-4784-bdd6-992eac84f23e",
      "revision": 0,
      "revisionTs": 1528712820,
      "createdTs": 1528712820,
      "type": "weir",
      "latlng": [46797717,11599884],
      "note": {
        "en": "Danger! scout before running, avoid in high water conditions"
      }
    },
    {
      "id": "9cb9d345-90b3-4226-9671-11119c667002",
      "revision": 1,
      "revisionTs": 1528715820,
      "createdTs": 1528713820,
      "type": "dangerTemp",
      "latlng": [46788527,11612400],
      "note": {
        "en": "Tree obstructs 3/4 of the river. Pass all the way to river left"
      }
    }
  ],
  "userNotes": [
    {
      "status": "ok",
      "id": "6792bf56-fcb5-43e7-81d0-46ed5f679a3b",
      "riverSectionId": "5b8a3684-bf0e-4476-b302-bb246183928c",
      "createdTs": 1528726000,
      "revisionTs": 1528726000,
      "category": "logistics",
      "note": {
        "en": "The current put in coordinates are not quite right. Actual put in is about 20 meters upstream at 46.808670, 11.570629"
      },
      "translations": {},
      "customFields": {},
      "refPoiUuid": "6402c49c-b8ed-4d99-80b6-20c6bf83fc34",
      "refNoteUuid": null
    },
    {
      "status": "merged",
      "id": "c9b42481-a252-4a10-abbe-22950046e655",
      "riverSectionId": "5b8a3684-bf0e-4476-b302-bb246183928c",
      "createdTs": 1528714266,
      "revisionTs": 1528715820,
      "category": "dangerTemporary",
      "note": {
        "en": "The tree moved and now obstructs 3/4 of the river. It's possible to pass all the way to river left"
      },
      "translations": {},
      "customFields": {
        "rivermap": {
          "legacyId": 623
        }
      },
      "refPoiUuid": "9cb9d345-90b3-4226-9671-11119c667002",
      "refNoteUuid": "02664c1f-717d-4fbb-8ca3-74c15967cd46"
    },
    {
      "status": "outdated",
      "id": "02664c1f-717d-4fbb-8ca3-74c15967cd46",
      "riverSectionId": "5b8a3684-bf0e-4476-b302-bb246183928c",
      "createdTs": 1528712266,
      "revisionTs": 1528712266,
      "category": "dangerTemporary",
      "note": {
        "en": "Dangerous river-wide tree just upstream of the final rapid"
      },
      "customFields": {
        "rivermap": {
          "legacyId": 612
        }
      },
      "translations": {},
      "refPoiUuid": null,
      "refNoteUuid": null
    }
  ],
  "license": "https://api.rivermap.org/doc/v2/#license"
}

List all River Sections.

THROTTLING

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

HTTP REQUEST

GET https://api.rivermap.org/v2/sections

RETURN VALUES

Property Type Description
sections list of RiverSection All River Sections
rivers list of River NOT YET SUPPORTED
Rivers referenced by the listed River Sections
regions list of Region NOT YET SUPPORTED
Regions referenced by the listed River Sections
pois list of POI POIs referenced by the listed River Sections
userNotes list of UserNote NOT YET SUPPORTED
UserNotes associated to the listed River Sections
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

User Notes API

List Recent User Notes

curl https://api.rivermap.org/v2/notes?key=AUTH_KEY

GET /v2/notes HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 120,
  "notes": [
    {
      "status": "ok",
      "id": "6792bf56-fcb5-43e7-81d0-46ed5f679a3b",
      "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
      "createdTs": 1528726000,
      "revisionTs": 1528726000,
      "category": "dangerCleared",
      "note": {
        "en": "Tree is not there anymore"
      },
      "translations": {},
      "customFields": {},
      "refPoiUuid": null,
      "refNoteUuid": "6d13cb32-7238-4c2c-8602-13304addec08"
    },
    {
      "status": "outdated",
      "id": "6d13cb32-7238-4c2c-8602-13304addec08",
      "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
      "createdTs": 1528711420,
      "revisionTs": 1528725333,
      "category": "dangerTemporary",
      "note": {
        "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river RIGHT.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
      },
      "translations": {
        "it": "Albero a tutto fiume alle coordinate 46.124321,7.128343. Trasbordo da riva DESTRA.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nVedi anche [questo post su Facebook](https://facebook.com/post-about-tree-in-river)"
      },
      "customFields": {},
      "refPoiUuid": null,
      "refNoteUuid": null
    }
  ],
  "license": "https://api.rivermap.org/doc/v2/#license"
}

List recent user-submitted notes for all River Sections

THROTTLING

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

HTTP REQUEST

GET https://api.rivermap.org/v2/notes[?from=YYYYMMddHHmm|mm]

QUERYSTRING PARAMETERS

Property Type Description
from DateTime or int Optional. Can be either an absolute timestamp (e.g: 201808261810) or a relative time expressed in minutes (e.g.: 60). If not specified defaults to 1440 (i.e.: all notes submitted in the last 24 hours)

RETURN VALUES

Property Type Description
notes list of UserNote All User Notes matching the search criteria
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

List Section User Notes

curl https://api.rivermap.org/v2/sections/1612ffdd-c505-4d0e-9aa7-0bf7cdc1efe6/notes?key=AUTH_KEY

GET /v2/section/1612ffdd-c505-4d0e-9aa7-0bf7cdc1efe6/notes HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 120,
  "notes": [
    {
      "status": "ok",
      "id": "6792bf56-fcb5-43e7-81d0-46ed5f679a3b",
      "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
      "createdTs": 1528726000,
      "revisionTs": 1528726000,
      "category": "dangerCleared",
      "note": {
        "en": "Tree is not there anymore"
      },
      "translations": {},
      "customFields": {},
      "refPoiUuid": null,
      "refNoteUuid": "6d13cb32-7238-4c2c-8602-13304addec08"
    },
    {
      "status": "outdated",
      "id": "6d13cb32-7238-4c2c-8602-13304addec08",
      "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
      "createdTs": 1528711420,
      "revisionTs": 1528725333,
      "category": "dangerTemporary",
      "note": {
        "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river RIGHT.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
      },
      "translations": {
        "it": "Albero a tutto fiume alle coordinate 46.124321,7.128343. Trasbordo da riva DESTRA.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nVedi anche [questo post su Facebook](https://facebook.com/post-about-tree-in-river)"
      },
      "customFields": {},
      "refPoiUuid": null,
      "refNoteUuid": null
    }
  ],
  "license": "https://api.rivermap.org/doc/v2/#license"
}

List all user-submitted notes for the given River Section

THROTTLING

Leaky bucket (size:5, refill: 1 per second)

HTTP REQUEST

GET https://api.rivermap.org/v2/sections/:sectionId/notes[?from=YYYYMMddHHmm|mm]

PATH PARAMETERS

Property Type Description
sectionId UUID Identifies the River Section

QUERYSTRING PARAMETERS

Property Type Description
from DateTime or int Optional. Can be either an absolute timestamp (e.g: 201808261810) or a relative time expressed in minutes (e.g.: 60). If not specified defaults to “the beginning of time” (e.g.: all section notes are returned)

RETURN VALUES

Property Type Description
notes list of UserNote All User Notes matching the search criteria
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Submit User Note

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://api.rivermap.org/v2/notes?key=AUTH_KEY

POST /v2/notes HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org
Content-Type: application/json

{
  "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
  "category": "dangerTemporary",
  "note": {
    "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river left.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
  },
  "refPoiUuid": null,
  "refNoteUuid": null
}

The above command returns JSON structured like this:

{
  "elapsedMs": 75,
  "note": {
    "status": "ok",
    "id": "6d13cb32-7238-4c2c-8602-13304addec08",
    "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
    "createdTs": 1528711420,
    "revisionTs": 1528711420,
    "category": "dangerTemporary",
    "note": {
      "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river left.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
    },
    "translations": {},
    "customFields": {},
    "refPoiUuid": null,
    "refNoteUuid": null
  },
  "editToken": "c03891e8-b3fc-4d15-96fb-999eb2af75f3",
  "license": "https://api.rivermap.org/doc/v2/#license"
}

Submit a user-note for the given River Section.

THROTTLING

Leaky bucket (size:5, refill: 1 per minute)

HTTP REQUEST

POST https://api.rivermap.org/v2/notes

REQUEST BODY

Property Type Description
note SubmitUserNoteRequest object Note data

RETURN VALUES

Property Type Description
note UserNote The inserted User Note
editToken String A time-limited token that can be used to edit the note (to let the user that submitted the note find and correct inaccuracies). See Update a User Note
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Update a User Note

curl -H "Content-Type: application/json" -X PATCH -d 'insert request body below' https://api.rivermap.org/v2/notes/c03891e8-b3fc-4d15-96fb-999eb2af75f3?key=AUTH_KEY

PATCH /v2/notes/c03891e8-b3fc-4d15-96fb-999eb2af75f3 HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org
Content-Type: application/json

{
  "note": {
    "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river RIGHT.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
  }
}

The above command returns JSON structured like this:

{
  "elapsedMs": 75,
  "note": {
    "status": "ok",
    "id": "6d13cb32-7238-4c2c-8602-13304addec08",
    "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
    "createdTs": 1528711420,
    "revisionTs": 1528717888,
    "category": "dangerTemporary",
    "note": {
      "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river RIGHT.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
    },
    "translations": {},
    "customFields": {},
    "refPoiUuid": null,
    "refNoteUuid": null
  },
  "editToken": "c03891e8-b3fc-4d15-96fb-999eb2af75f3",
  "license": "https://api.rivermap.org/doc/v2/#license"
}

Update a recently-submitted user-note. This is meant to let a user correct her own note in case she spots an error right after having submitted it. Notes remain editable for up to 10 minutes after being submitted. After that time notes cannot be updated anymore, with the exception of translations: those can be added/updated at any time.

THROTTLING

Leaky bucket (size:5, refill: 1 per minute)

HTTP REQUEST

PATCH https://api.rivermap.org/v2/notes/:editToken

PATH PARAMETERS

Property Type Description
editToken UUID The edit token returned by Submit User Note

REQUEST BODY

Property Type Description
note UpdateUserNoteRequest object Note data

RETURN VALUES

Property Type Description
note UserNote The updated User Note
editToken String A time-limited token that can be used to (further) edit the note
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Delete a User Note

curl -X DELETE https://api.rivermap.org/v2/notes/c03891e8-b3fc-4d15-96fb-999eb2af75f3?key=AUTH_KEY

DELETE /v2/notes/c03891e8-b3fc-4d15-96fb-999eb2af75f3 HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org

The above command returns JSON structured like this:

{
  "elapsedMs": 75,
  "note": {
    "status": "ok",
    "id": "6d13cb32-7238-4c2c-8602-13304addec08",
    "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
    "createdTs": 1528711420,
    "revisionTs": 1528717888,
    "category": "dangerTemporary",
    "note": {
      "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river RIGHT.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
    },
    "translations": {},
    "refPoiUuid": null,
    "refNoteUuid": null
  },
  "license": "https://api.rivermap.org/doc/v2/#license"
}

Delete a recently-submitted user-note. This is meant to let a user delete her own note in case she realizes it submitted it by mistake. Notes can be deleted for up to 10 minutes after being submitted. After that time notes cannot be deleted anymore.

THROTTLING

Leaky bucket (size:5, refill: 1 per minute)

HTTP REQUEST

DELETE https://api.rivermap.org/v2/notes/:editToken

PATH PARAMETERS

Property Type Description
editToken UUID The edit token returned by Submit User Note

RETURN VALUES

Property Type Description
note UserNote The deleted User Note
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Submit User Note Translation

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://api.rivermap.org/v2/notes/6d13cb32-7238-4c2c-8602-13304addec08/translations?key=AUTH_KEY

POST /v2/notes/6d13cb32-7238-4c2c-8602-13304addec08/translations HTTP/1.0
Accept: application/json
X-Key: YOUR API KEY
Host: api.rivermap.org
Content-Type: application/json

{
  "it": "Albero a tutto fiume alle coordinate 46.124321,7.128343. Trasbordo da riva DESTRA.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nVedi anche [questo post su Facebook](https://facebook.com/post-about-tree-in-river)"
}

The above command returns JSON structured like this:

{
  "elapsedMs": 75,
  "note": {
    "status": "ok",
    "id": "6d13cb32-7238-4c2c-8602-13304addec08",
    "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
    "createdTs": 1528711420,
    "revisionTs": 1528725333,
    "category": "dangerTemporary",
    "note": {
      "en": "River-wide tree at coordinates 46.124321,7.128343. Portage on river RIGHT.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nSee also [this Facebook post](https://facebook.com/post-about-tree-in-river)"
    },
    "translations": {
      "it": "Albero a tutto fiume alle coordinate 46.124321,7.128343. Trasbordo da riva DESTRA.\nFoto: ![alt text](https://rivermap.org/images/upload/39acacd4-598c-417f-888e-f042d0c43b67).\nVedi anche [questo post su Facebook](https://facebook.com/post-about-tree-in-river)"
    },
    "customFields": {},
    "refPoiUuid": null,
    "refNoteUuid": null
  },
  "editToken": "c03891e8-b3fc-4d15-96fb-999eb2af75f3",
  "license": "https://api.rivermap.org/doc/v2/#license"
}

Submit a translation for a given user-note.

Note: Translations for languages that are already available in the original note are discarded. E.g.: if the original note was submitted in English and Italian, it’s not possible to provide English or Italian translations as those would overwrite the original text.

THROTTLING

Leaky bucket (size:5, refill: 1 per minute)

HTTP REQUEST

POST https://api.rivermap.org/v2/notes/:noteId/translations

PATH PARAMETERS

Property Type Description
noteId UUID The note id

REQUEST BODY

Property Type Description
translations map[LanguageCode]String Translations

RETURN VALUES

Property Type Description
note UserNote The updated User Note
license String Link to license info
elapsedMs int Time required to fulfill the request, in milliseconds

Object Definitions

Station objects

Station Object properties

//
// ONLINE STATION
//
{
  "id": "04d0980c-a251-422a-a2c0-e699c84936fe",
  "type": "online",
  "revision": 5,
  "revisionTs": 1524914164,
  "isActive": true,
  "sensors": ["level", "flow"],
  "name": "Malé",
  "riverId": null,
  "river": {
    "it": "Noce"
  },
  "state": "Trentino",
  "countryCode": "IT",
  "dataSourceId": "bc5faa96-9ee1-4668-b445-44346603eec9",
  "sourceLinks": {
    "it": {
      "level": "http://www.floods.it/public/GraficiPub.php?Sensore=11732&Argomento=0",
      "flow": "http://www.floods.it/public/GraficiPub.php?Sensore=18711&Argomento=0"
    }
  },
  "parserConfigs": "11732,18711",
  "latlng": [
    46347113,
    10913822
  ],
  "observationFreqMins": 15,
  "publishingFreqMins": 15,
  "note": {
    "it": "Alcune note sull'idrometro...",
    "en": "Some relevant notes about the station..."
  },
  "synthetic": null
}

//
// MANUAL STATION
//
{
  "id": "1b0af9ed-25e1-4d6e-bf88-ef529fb801f8",
  "type": "manual",
  "revision": 5,
  "revisionTs": 1524914164,
  "isActive": true,
  "sensors": ["level"],
  "name": "Silisia Imbarco",
  "riverId": null,
  "river": {
    "it": "Silisia"
  },
  "state": "Friuli-Venezia Giulia",
  "countryCode": "IT",
  "dataSourceId": null,
  "sourceLinks": {},
  "parserConfigs": "",
  "latlng": [
    46255338,
    12699675
  ],
  "observationFreqMins": -1,
  "publishingFreqMins": -1,
  "note": {
    "it": "Per stazioni manuali è importante che queste note spieghino in dettaglio  dove è posizionata e come arrivare all'asta fisica dell'idrometro",
    "en": "For manual stations it is paramount that these notes explain in good detail where the physical reference is located and how to get to it"
  },
  "synthetic": null
}

//
// SYNTHETIC STATION
//
{
  "id": "5a2bb96e-779d-4ab7-a489-5ba3cab391ec",
  "type": "synthetic",
  "revision": 5,
  "revisionTs": 1524914164,
  "isActive": true,
  "sensors": ["flow"],
  "name": "Bidente di Pietrapazza",
  "riverId": null,
  "river": {
    "it": "Adige",
    "de": "Etch"
  },
  "state": "Emilia-Romagna",
  "countryCode": "IT",
  "dataSourceId": null,
  "sourceLinks": {},
  "parserConfigs": "",
  "latlng": [
    45439000,
    10994428
  ],
  "observationFreqMins": 30,
  "publishingFreqMins": 30,
  "note": {
    "it": "Alcune note sull'idrometro virtuale, tipo cos'è che viene calcolato e perchè...",
    "en": "Some relevant notes about the synthetic station, like what exactly is computed and why..."
  },
  "synthetic": {
    "aliases": {
      "a6f3a6eb-2f8d-4200-8dc6-fcd56a5b3cf6": "Rilascio_Diga_Ridracoli",
      "83164fcb-1ed4-472e-b2b5-ea183aaf2673": "S_Sofia"
    },
    "values": {
      "m3s": "S_Sofia - Rilascio_Diga_Ridracoli"
    },
    "toleranceSecs": 5400
  }
}

This object models 3 types of stations/gauges:

Other visual references (rocks, banks, etc) are modeled as POIs with type=altGauge

Property Type Description
id UUID Globally unique Gauging Station id
type enum One of:
  • online: readings are provided by the water authority owning the gauge
  • manual: readings are provided by users based on direct observation of a physical measuring stick
  • synthetic: readings are computed from readings from other gauges via a formula (e.g.: sum of the flows from 2 tributaries)
revision int Incremented every time details for this station are edited/updated
revisionTs int Updated every time revision is incremented. Unix epoch. Seconds since Jan 01 1970 (UTC)
isActive boolean true if Rivermap is collecting readings from this station, false otherwise (station is “dormant”)
sensors list of enum List of sensors supported by the station. Supported enum values are level and flow
name String Gauging station name (as named by the owning source/authority)
riverId UUID NOT YET SUPPORTED
Id if the River monitored by this station
river map[LanguageCode]String River being monitored by this station
countryCode String ISO 3166-1 alpha-2 Country Code
state String State, region or administrative area, where applicable (depends on country)
latlng LatLng Gauging station location. Null if location is unknown
dataSourceId UUID Id of the entity/authority publishing station data
sourceLinks map[LanguageCode]SourceLink Direct links to the station as published online by the owning authority, where available, or a generic link to the water authority’s page if direct per-station links are not available, or empty if nothing at all is available (e.g.: manual/crowdsourced and synthetic stations)
Links to pages with graphs are preferred over pages with tables or with just the current value.
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)
observationFreqMins int How often the station acquires new samples. Set to -1 if there is no fixed observation frequency because:
- this station is listed-but-not-active (samples are not being actively read and stored)
- this is a manual/crowdsourced gauge
- the samples are acquired erratically
publishingFreqMins int How often new samples are (usually) published by this station, -1 if there is no fixed publication frequency.
Usually the same as observationFreqMins but not necessarily (e.g.: some stations acquire samples every 15 mins but only publish them in bulk every X hours)
note map[LanguageCode]String Notes about this gauging station, curated by experts/editors. Examples:
- influenced by erratic dam release, can be unreliable
- often gets stuck in winter in freezing conditions
synthetic SyntheticGauge Only populated for synthetic-type stations, null otherwise 
{
  "level": "http://www.floods.it/public/GraficiPub.php?Sensore=11770&Argomento=0",
  "flow": "http://www.floods.it/public/GraficiPub.php?Sensore=18707&Argomento=0"
}
Property Type Description
level URL Direct link to level graph as provided by the Source, null if direct link is not provided
flow URL Direct link to flow graph as provided by the Source, null if direct link is not provided

ReadingsRange object properties

{
  "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
cm list of TimestampedValue Level readings, in centimeters, sorted by timestamp (ascending)
m3s list of TimestampedValue Flow readings, in cubic meters per second, sorted by timestamp (ascending)

SyntheticGauge object properties

{
  "aliases": {
    "a6f3a6eb-2f8d-4200-8dc6-fcd56a5b3cf6": "Geissmattbrücke",
    "83164fcb-1ed4-472e-b2b5-ea183aaf2673": "Kl_Emme_Emmen"
  },
  "values": {
    "m3s": "Geissmattbrücke.m3s + Kl_Emme_Emmen.m3s"
  },
  "toleranceSecs": 5400
}
Property Type Description
aliases map[UUID]String Maps stationId to an alias used in formulas
values map[StorageUnit]Formula Maps output unit to the formula computing it.
toleranceSecs The maximum range, in seconds, between oldest and youngest component (i.e.: reading from a station) of the formula for it to yield a measurement

Source Object properties

{
  "id": "06ab69d2-c518-4fe4-89e3-a9edc24bd5b7",
  "name": "ARPA Veneto",
  "shortName": "ARPAV",
  "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/",
  "countryCode": "IT"
}
Property Type Description
id UUID Globally unique Source/Authority Id
name String Source name (full)
shortName String Source name (short)
licensingTerms String Licensing terms / ToS (Markdown format)
website String Link to website
countryCode String ISO 3166-1 alpha-2 Country Code of this source. “XX” in case of transnational sources.

Formula Object properties

// Simple formula example
"Geissmattbrücke.m3s + Kl_Emme_Emmen.m3s"
// Complex formula example
"(0.95 * Schönenbach.m3s + 0.102 * Tiefenbach.m3s + 0.25 * Oberstaufen.m3s + 1.06 * Reuthe.m3s + 0.99 * Kälberweide.m3s) - MAX( 0, (Hittisau.m3s - (2.75 * Kälberweide.m3s + 0.67 * Schönenbach.m3s + 0.345 * Oberstaufen.m3s)) )"

A formula where components are expressed as “station-id-alias” dot StorageUnit. Currently supports parentesis, basic math operators (+,-,*,/) and a limited set of functions:

RiverSection objects

RiverSection Object properties

{
  "id": "37765303-50ec-4b43-add6-6f8db6bafafa",
  "revision": 11,
  "revisionTs": 1528712750,
  "createdTs": 1528712750,
  "riverOrdinal": 0,
  "countryCode": "IT",
  "riverId": null,
  "river": {
    "en": "name-of-the-river",
    "it": "nome-del-fiume"
  },
  "regionId": "10b22e7c-0fbd-42ea-a5d9-4426d40163b4",
  "sectionName": {
    "en": {
      "formattedName": "Upper 1: White teeth of death [below weir at A - reservoir at B]",
      "qualifier": "Upper 1"
      "name": "White teeth of death",
      "from": "below weir at A",
      "to": "reservoir at B",
      "isCanonical": true
    },
    "de":{
      "formattedName": "Oberer 1 [unterhalb Wehr bei A - Stausee bei B]",
      "qualifier": "Oberer 1",
      "name": "",
      "from": "unterhalb Wehr bei A",
      "to": "Stausee bei B",
      "isCanonical": false
    }
  },
  "category": "whitewater",
  "grade": "IV-V",
  "spotGrades": ["VI", "X", "X"],
  "lengthMt": 8000,
  "verticalMt": 240,
  "durationMins": 180,
  "calibration": {
    "stationId": "bb92231a-886a-4ef9-8974-9ae265ed6686",
    "isIndirect": false,
    "unit": "m",
    "lw": 0.25,
    "mw": null,
    "mwMin": null,
    "mwMax": null,
    "hw": 0.9,
    "lastReviewedTs": 1525564800,
    "note": {
      "it": "Alcune note sulle calibrazioni",
      "en": "Some relevant notes about calibrations"
    }
  },
  "calibrationsAlt": [],
  "putInLatLng": [
    46393207,
    10855551
  ],
  "takeOutLatLng": [
    46358024,
    10914533
  ],
  "riverGuideLinks": {
    "it": "[Descrizione su CKFiumi](https://www.ckfiumi.net/consulta.phtml/190/182)",
    "en": "A description of the lower section is [here](http://yaddayadda/guides/rabbies).\nThe ckfiumi guide (in italian) is probably more complete"
  },
  "poiIds": [
    "06c4599d-8331-4eef-8cba-8a4498c52067",
    "819646e1-9495-42b3-9e44-6e915542b3f1",
    "bd545a96-d915-4cee-beb5-a12671466dec",
    "c346bb25-821b-40bd-a601-a9ee70aed5a2",
    "f9633818-d566-423c-bd6f-0b495f7d9ac2",
    "f5cee75c-3f0f-4d9a-93fa-14c97cb6ba84",
    "c0acbf02-6ae2-4b37-ba05-f7bcaa74726f",
    "d94c8841-bcd0-4791-bb63-24f2dc2af7c7"
  ],
  "closures": [
    {
      "type": "permanent",
      "reason": {
        "en": "banned by authority"
      }
    },
    {
      "type": "temporary",
      "reason": {
        "en": "body recovery"
      },
      "from": "2018-07-12",
      "to": null
    },
    {
      "type": "seasonal",
      "reason": {
        "en": "mating period for endangered local species"
      },
      "from": "06-01",
      "to": "09-01"
    },
    {
      "type": "daily",
      "reason": {
        "en": "mutual agreement with local fishermen"
      },
      "from": "18:00",
      "to": "09:00"
    }
  ],
  "customFields": {
    "riverzone": {
      "legacyId": 4,
      "categoryTags": ["rockgarden", "steep", "alpine"]
    },
    "rivermap": {
      "legacyId": 274,
      "wwStars": 4
    }
  }
}
Property Type Description
id UUID Globally unique River Section Id
revision int Incremented every time details for this section are edited/updated (user notes excluded)
revisionTs int Updated every time revision is incremented. Unix epoch. Seconds since Jan 01 1970 (UTC)
createdTs int When this Section was first added. Unix epoch. Seconds since Jan 01 1970 (UTC)
riverOrdinal int Used for ordering same-riverId river sections from upper to lower. Defaults to 0
countryCode String ISO 3166-1 alpha-2 Country Code of the canonical put-in
riverId UUID NOT YET SUPPORTED
River identifier
river map[LanguageCode]String River name
regionId UUID Region identifier. A region needs not be administrative or political and is meant to represent a meaningful grouping of rivers.
Mountain areas (Vosges, Alpi Marittime) or catchments (Haute Garonne, Valsesia) can sometimes be useful region names
sectionName map[LanguageCode]SectionName Internationalized river section name
category enum One of whitewater, play, slalom, flatwater or drop
grade Grade Difficulty rating for this section
spotGrades list of Grade Spot grades for this section.
Multiple occurrences of the same spot grade are supported as in [“X”, “X”] to indicate that there are two unrunnable spots
lengthMt int Length of section in meters. Set to -1 if unknown
verticalMt int Vertical height of the section from put-in to take-out in meters. Set to -1 if unknown
durationMins int How much time it usually takes to run the section under medium-water conditions and not already knowing it, in minutes. Set to -1 if unknown
calibration Calibration Primary section calibration
calibrationsAlt list of Calibration Alternative, secondary and/or experimental section calibrations
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 (can happen when category is play, slalom or drop)
riverGuideLinks map[LanguageCode]String Links to guidebooks. Text in (Markdown format)
poiIds list of UUID References to Point of Interests about this section (examples are: alternate put-ins/take-outs, parking locations, dangers, restaurants, etc)
closures list of Closure The section is closed if any condition matches
customFields map[String]map[String]object Custom per-affiliated-project fields

SectionName Object properties

{
  "formattedName": "Upper 1: White teeth of death [below weir at A - reservoir at B]",
  "qualifier": "Upper 1",
  "name": "White teeth of death",
  "from": "below weir at A",
  "to": "reservoir at B",
  "isCanonical": true
}
Property Type Description
formattedName String Full section name. Formatted, based on what name components are available, as one of:
  • qualifier: name [from - to]
  • qualifier [from - to]
  • name [from - to]
  • [from - to]
  • qualifier: name
  • qualifier
  • name
  • (empty string)
qualifier String Optional: a common, easily translatable ordinal qualifier like: lower, middle, higher, upper, upper-upper
name String Optional: a well known name for the section. E.g.: Alpine Sprint
from String Optional (unless to is provided): put-in place name (or place description) like: Bozzo, Lake, Reservoir, Sawmill, Wooden bridge
to String Optional (unless from is provided): take-out place name (or place description)
isCanonical bool True if this is a well known name that locals will recognise, false if it’s the result of a translation

Grade Object properties

"I", "I+", "I-II", "II-",
"II", "II+", "II-III", "III-",
"III", "III+", "III-IV", "IV-",
"IV", "IV+", "IV-V", "V-",
"V", "V+", "V-VI", "VI-",
"VI",
"X" // unrunnable

WW ICF grades plus half-grades

Calibration Object properties

{
  "stationId": "bb92231a-886a-4ef9-8974-9ae265ed6686",
  "isIndirect": false,
  "unit": "m",
  "lw": 0.25,
  "mw": null,
  "mwMin": null,
  "mwMax": null,
  "hw": 0.9,
  "lastReviewedTs": 1525564800,
  "note": {
    "it": "Alcune note sulle calibrazioni",
    "en": "Some relevant notes about calibrations"
  }
}
Property Type Description
stationId UUID Id of the referenced Gauging Station
isIndirect bool True if the Gauging Station is very far upstream or downstream, or on a different but related river (e.g.: a tributary)
unit CalibrationUnit The unit calibration data is expressed in
lw float Optional: Low water value. Below this level you can walk down the river
mw float Optional: Medium water value. Section grade, spotGrades and durationMin always refer to these water conditions
hw float Optional: High water value. Very subjective and often unreliable. The general idea is that above this level you should not put in
mwMin float Optional and experimental: the lower range of medium water.
While in this range grade, spotGrades and durationMin are consistent and the run remains enjoyable.
A paddler that never run this section would want to run it in this range
mwMax float Optional and experimental: the upper range of medium water. See mwMin. Above this level difficulties increase and the reported grade does not apply anymore
lastReviewedTs int The last time these calibrations were reviewed
note map[LanguageCode]String Calibration notes curated by the editor

Closure Object properties

// permanent closure
{
  "type": "permanent",
  "reason": {
    "en": "banned by authority"
  }
}

// temporary closure with no known end date
{
  "type": "temporary",
  "reason": {
    "en": "body recovery"
  },
  "from": "2018-07-12",
  "to": null
}

// seasonal closure
{
  "type": "seasonal",
  "reason": {
    "en": "mating period for endangered local species"
  },
  "from": "06-01",
  "to": "09-01"
}

// daily closure
{
  "type": "daily",
  "reason": {
    "en": "mutual agreement with local fishermen"
  },
  "from": "18:00",
  "to": "09:00"
}
Property Type Description
type enum One of permanent, temporary, seasonal, daily
reason map[LanguageCode]String Reason details, curated by the editor
from String Closure start date/time.
null for permanent closures, DateString for temporary and seasonal, TimeString for daily
to String Closure end date/time. Formatted same as from. Can be null for temporary closures if the end of the closure period is unknown.

Poi Object properties

{
  "id": "819646e1-9495-42b3-9e44-6e915542b3f1",
  "revision": 1,
  "revisionTs": 1528712750,
  "createdTs": 1528711420,
  "type": "putInAlt",
  "latlng": [46741463, 11205582],
  "note": {
    "en": "Put-in here to run the IV-grade rapid right before the classic put-in"
  },
  "label": "",
  "poly": [
    [46720887, 11193480],
    [46720159, 11192868],
    [46719409, 11192772],
    [46718210, 11192804],
    [46717298, 11192911]
  ],
  "polyStyle": "path"
}
Property Type Description
id UUID Globally unique Poi id
revision int Incremented every time details for this Poi are edited/updated
revisionTs int Updated every time revision is incremented OR when details for this Poi are re-validated. Unix epoch. Seconds since Jan 01 1970 (UTC)
createdTs int When this Poi was first added. Unix epoch. Seconds since Jan 01 1970 (UTC)
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
intake: location of an intake relevant to gauge current flow
outfall: location of an outfall relevant to gauge current flow
latlng LatLng Poi location
note map[LanguageCode]String Optional notes about this Poi, curated by the editor. Empty map if no notes
label String Optional. Used to label the map-icon and make it easier to differentiate this Poi from identical-type ones (e.g.: intakes / outfalls)
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

User Note objects

UserNote Object properties

{
  "id": "6d13cb32-7238-4c2c-8602-13304addec08",
  "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
  "createdTs": 1528711420,
  "revisionTs": 1528712750,
  "category": "dangerTemporary",
  "customFields": {
    "rivermap": {
      "legacyId": 1734
    }
  },
  "status": "ok",
  "note": {
    "it": "bla bla bla [link](http://a.b.com)",
    "en": "blah blah blah. More info (in italian) at [link](http://a.b.com)"
  },
  "translations": {
    "de": "blah blah blah in german"
  },
  "refPoiId": null,
  "refNoteId": null
}
Property Type Description
id UUID Globally unique UserNote id
riverSectionId UUID Id of the RiverSection this notes refers to
createdTs int When this Note was first added. Unix epoch. Seconds since Jan 01 1970 (UTC)
revisionTs int Updated every time this note is updated. Unix epoch. Seconds since Jan 01 1970 (UTC)
category enum One of:
  • urgent: Urgent message: emergency in progress, lost equipment, …
  • dangerTemporary: Temporary danger: tree, works, landslide, …
  • dangerCleared: Danger cleared
  • dangerPermanent: Permanent danger: weir, syphon, undercut, …
  • calibration: Calibration notes
  • difficulty: Difficulty
  • currentConditions: Current conditions
  • regulations: Rules and regulations: permanent restrictions, seasonal opening/closure, …
  • info: General description, video, webcam, gallery, river guide, …
  • logistics: Access, parking, camping, …
customFields map[String]map[String]object Optional. Custom per-affiliated-project fields
status enum One of:
  • ok: UIs should display the note
  • merged: The editor reviewed the note and incorporated it into the curated section data. UIs should collapse/hide the note by default
  • outdated: The editor flagged the note as outdated. UIs should collapse/hide the note by default
  • spam: The editor flagged the note as spam. Spam is filtered by the system by default
note map[LanguageCode]String Note text as entered by the user (markdown format)
translations map[LanguageCode]String Community-provided translations of the note text
refPoiId UUID Optional: Id of a Poi referenced by this note. E.g.: a note providing further details about a parking-type Poi
refNoteId UUID Optional: Id of another UserNote referenced by this note.
E.g.: a dangerCleared note providing updated info about a previous temporaryDanger note.
UIs are encouraged to display the note followed by the indented text of the referenced note (as in an email thread)

SubmitUserNoteRequest Object properties

{
  "riverSectionId": "37765303-50ec-4b43-add6-6f8db6bafafa",
  "category": "dangerTemporary",
  "customFields": {
    "rivermap": {
      "legacyId": 623
    }
  },
  "note": {
    "it": "bla bla bla [link](http://a.b.com)",
    "en": "blah blah blah. More info (in italian) at [link](http://a.b.com)"
  },
  "refPoiId": null,
  "refNoteId": null
}
Property Type Description
riverSectionId UUID Id of the RiverSection this notes refers to
category enum See UserNote
customFields map[String]map[String]object Optional. Custom per-affiliated-project fields
note map[LanguageCode]String Note text entered by the user (markdown format)
refPoiId UUID Optional. Id of a Poi referenced by this note. E.g.: a note providing further details about a parking-type Poi
refNoteId UUID Optional. Id of another UserNote referenced by this note.
E.g.: a dangerCleared note providing updated info about a previous temporaryDanger note.
UIs are encouraged to display the note followed by the indented text of the referenced note (as in an email thread)

UpdateUserNoteRequest Object properties

{
  "category": "dangerPermanent",
  "note": {
    "it": "testo corretto",
    "en": "corrected text"
  },
  "refPoiId": null,
  "refNoteId": null
}
Property Type Description
category enum Optional. If specified overwrites the current value
note map[LanguageCode]String Optional. If specified fully overwrites the current value (the whole map).
Note: if the update adds text in a new language, it will replace any pre-existing contributed translation for that language
refPoiId UUID Optional. If specified overwrites the current value
refNoteId UUID Optional. If specified overwrites the current value

Miscellaneous objects

River Object properties

{
  "id": "21e279ab-3eee-4312-8394-5a90e09859e3",
  "names": {
    "it": "Passirio",
    "de": "Passer"
  }
}
Property Type Description
id UUID Globally unique River Id
names map[LanguageCode]String Internationalized river name

Region Object properties

{
  "id": "10b22e7c-0fbd-42ea-a5d9-4426d40163b4",
  "names": {
    "it": "Trentino"
  }
}
Property Type Description
id UUID Globally unique Region Id
names map[LanguageCode]String Internationalized region name

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

"en" // english
"it" // italian
"fr" // french
"de" // german
"pt" // portuguese
"es" // spanish
"el" // greek
"no" // norwegian
"sv" // swedish
"cs" // czech
"sl" // slovenian
"bs" // bosnian
"hr" // croatian
"ru" // russian

ISO 639-1 codes

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.

CalibrationUnit Object properties

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

Enumeration of supported calibration units represented as a string.

Allowed values are cm, m, ft for levels and m3s, cfs, lts 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.

TimeString Object properties

// 6:23pm
"18:23"
// 2:15am
"02:15"
// noon
"12:00"
// midnight
"00:00"

Time-of-day represented as a string formatted as HH24:mm.

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
 
2020/04/19 Added the Getting Started and Test with Postman Chapters.
Added notice about User Notes API not being available (yet)
Added links and references to Rivermap
2020/01/07 Updated and extended URL parameters used by the List Stations endpoint
2019/12/24 Updated documentation about User Notes and River Sections (replaced PoiId object with simple UUID string)
2019/03/25 Documented Source endpoint
2019/03/25 Added License Terms section
2018/08/28 First draft revision





























































 

http+json shell