NVE logo

NVE Hydrological API (HydAPI) - API documentation

Introduction to NVE's Hydrological API

NVE Hydrological API (HydAPI) is a is a RESTful API that provides access to NVE's (The Norwegian Water Resources and Energy Directorate) archive of historical and active observed time series. The time series are continuously updated with the latest observations from NVE's systems. The series exposed are the most common types like discharge, water stage, water temperature and other types. For full overview over all exposed time series types see the section for Parameters and Series. This page contains useful reference documentation related to usage of the HydAPI. Contact us if you have more detailed questions at this email: hydrology@nve.no

Quick-links

Table of contents

  1. Introduction
  2. License
  3. Terms of use
  4. Versioning
  5. Access to the API
  6. Getting started
  7. Returned response header
  8. Code examples on Github
  9. Guide for API usage - How things are structured
  10. Stations
  11. Series
  12. Parameters
  13. Rating curves
  14. Percentiles
  15. Observations - GET-method
  16. Observations - POST-method
  17. Changelog

License

The data provided by the API is licensed under the Norwegian License for Open Government Data (NLOD) which is compatible with CC Navngivelse 3.0 Norge (CC BY 3.0). Data is provided by the API "as is". It can contain erroneous or missing data. NVE does not take any responsibility for data that can give wrong or misleading information. When using data from this service, if possible, please refer to this service as origin of data.

Versioning

The API is currently version 1.0, and may be subject to change without any change in version number.

Access to the API

All requests to the API needs to be supported with an API-key in the request-header. We require this in order to provide all users a free, stable and reliable service.

Terms of use

Max response size

There is an upper limit of the number of data points you can retrieve in one request for observations. The request will terminate with an error if the query reaches this limit. If this happens, adjust the timespan in your query.

Max requests per time unit

Throttling: The API will only support a fixed number of requests from a client (API-key) per time unit, and will deny request when this limit is reached. Clients that violate this policy will be temporarily blocked by the API, and an error-message will show. Each response will contain information in the header (x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-reset). The start and end times in the metadata resolution list are updated approx. each 10 minutes, and the metadata for the stations and series is updated approx. each 4 hours. So the recommended requesting interval should be related to these updates.

Guidelines for efficient usage

Some guidelines for efficient usage:

Getting started

To be able to receive data from the HydAPI, you will need to provide an API-key with your request. The API-key is added in the request-header for all requests. An API-key is connected to an email-address, and will be used for traffic control (throttling) purposes. The email can also be used for information about the API (new versions and so on). Remember to keep your API-key stored in a secure place, as they are non-retrievable after generated. An API-key can be generated more than once on same email address, and old keys on the same email address are still valid even if new one are generated.

To generate a API-key, click here: Click here to create an API-key In Swagger view, click the button "Authorize", Swagger authorize button and then enter the API-key. This will automatically set the X-API-Key header in each call made to the API using the Swagger view. The API-key is added to the header for each request:
curl -X GET "https://hydapi.nve.no/api/v1/Parameters" -H "accept: application/json" -H "X-API-Key: XXXX---EXAMPLE KEY---XXXX"
For an additional code example implementing the API in C# look in the section: Code examples on github.

Returned response header

The response header includes information about; the input url, the API version, license information, the timestamp for when request is processed on the server, the processing time and the number of data records returned.

            
                    {
                        "currentLink": "https://hydapi.nve.no/api/v1/Observations?StationId=6.10.0&Parameter=1000&ResolutionTime=1440",
                        "apiVersion": "1.0",
                        "license": "https://data.norge.no/nlod/en",
                        "createdAt": "2019-09-23T07:52:12.3293346Z",
                        "queryTime": "00:00:00.0685120",
                        "itemCount": 1,
                        "data": [
                        {
                            ...(truncated)
                
            

Code examples on GitHub

Code examples for different languages is available in this GitHub repo.

Guide for API usage - How things are structured

NVE has stations all over Norway. A station is identified by a unique station-id. The station-id is a combination of three numbers separated by a "." (example 124.23.0). A station can contain several different measured series (time series). A series connected to a station is of one specific parameter type. A parameter gives the type of data the observed time series contains. Examples of parameters are discharge, water stage and water temperature. A time series has versions, and it is the one preferred version that is returned in the API. For detailed information about the input and output fields we refer to the API documented in Swagger documentation under the last part where all Models are listed.

Stations

The available stations can be found by giving no filter to the query, or the query can be filtered with parameters. The returned station contains metadata for the station, and lists out the available series with start and end dates. Start and end dates can be empty/null because this information is missing for the series. This does not mean that the series have no data. It is also possible to filter on active/non active stations. If no filter criteria are entered, all stations are returned. See Swagger the definition for Station (listed under models) for more detailed information.
Example url https://hydapi.nve.no/api/v1/Stations?CouncilName=Tynset&Active=OnlyActive

Series

All available series can be found by using this method. You can filter the search by supplying parameters filtering the list, giving e.g. series giving air-temperature (17) or series in a specific county. It is also possible to view only series with newer data than a certain time using the DataFrom field. A series contains metadata and a resolution list that views the different available time resolutions for the series. The supported time resolutions are raw/instantaneous (0), hour(60) and day(1440). The resolution-list shows the start and end times for observations for a specific resolution. The start and end times in the resolution list are updated approx. each 10 minutes. The metadata for the series is updated approx. each 180 minutes. If no filter criteria is given, all series are returned.
Example url https://hydapi.nve.no/api/v1/Series?StationId=1.200.0

Parameters

Parameter gives the type of data, like discharge, water stage or water temperature. This method lists all parameters available in the API. A parameter has a id (number internal defined in NVE) identifying that parameter type. Example “Discharge“ has parameter 1001. The unit is also viewed for the parameter
Example url https://hydapi.nve.no/api/v1/Parameters

Rating curves

The relation between the water stage and discharge is expressed as a “rating curve”. The rating curves query will list the discharge series with available rating curves. To find a specific rating curve for a series in this list, use the detailed rating curve search for a station-id. A rating curve can have different periods, to indicate what period the curve is valid for. A period will be limited by dtStartDate and dtEndDate. If dtEndData is null, the period is not ended. One period we can have one or more segments. One segment is starting on the minimum value, and ending on the maximum value. One segment starts where the prior ends. Within one segment the discharge is given by the formula Q (discharge)= constant *(input - zero)exp exponent
Example urls https://hydapi.nve.no/api/v1/Ratingcurves
https://hydapi.nve.no/api/v1/Ratingcurves/1.56.0

Example output.

            {
                 "currentLink": "https://hydapi.nve.no/api/v1/Ratingcurves/1.56.0",
                 "apiVersion": "1.0",
                 "license": "https://data.norge.no/nlod/en",
                 "createdAt": "2019-09-23T08:02:11.1472544Z",
                 "queryTime": "00:00:00.0003155",
                 "itemCount": 1,
                 "data": [
                 {
                    "stationId": "1.56.0",
                    "parameter": 1001,
                    "versionNo": 1,
                    "generationNo": 0,
                    "periodNo": 1,
                    "segmentNo": 1,
                    "constant": 12.9921,
                    "exponent": 2.2209,
                    "maximum": 160.74,
                    "minimum": 150.742,
                    "zero": -150.742,
                    "dtEstablDate": "1996-11-25T00:00:00",
                    "dtStartDate": "1992-06-30T00:00:00",
                    "dtEndDate": null
                }
                ]
            }
        

Percentiles

Percentiles-list is listing of series that have percentile statistics. To find the detailed information use the Percentile-details. The percentile percentages statistical information for a series are given for each day within a year.
Example urls https://hydapi.nve.no/api/v1/Percentiles
Get the stage parameter percentile-list for station 1.200.0:
https://hydapi.nve.no/api/v1/Percentiles/1.200.0/1000

Observations - GET-method

Observations can be retrieved using a GET-method.

The observations for a series can be found if the following fields are given;

The result can be filtered on quality types, correction types and within the given reference time. If no reference time is given, the API will return the last observed value.

Asking for two parameters on two stations in the same request, will give a result of four time series (if they exist). Note that there is a maximum number of parallel series you can ask for in one query, and the number of returned observations combined cannot exceed the total number of records. When asking for multiple series, there can be situations where the combination of station-id and parameter gives a non-existent series. The behaviour for the different variants are given below:

        
                    {
                        "currentLink": "https://hydapi.nve.no/api/v1/Observations?StationId=6.10.0&Parameter=1000&ResolutionTime=1440",
                        "apiVersion": "1.0",
                        "license": "https://data.norge.no/nlod/en",
                        "createdAt": "2019-09-23T11:16:51.788047Z",
                        "queryTime": "00:00:00.0511162",
                        "itemCount": 1,
                        "data": [
                        {
                            "stationId": "6.10.0",
                            "stationName": "Gryta",
                            "parameter": 1000,
                            "parameterName": "Vannstand",
                            "parameterNameEng": "Stage",
                            "serieVersionNo": 0,
                            "method": "Mean",
                            "unit": "m",
                            "observationCount": 1,
                            "observations": [
                            {
                                "time": "2019-09-22T11:00:00Z",
                                "value": 0.2255617,
                                "correction": 0,
                                "quality": 1
                            }
                            ]
                        }
                        ]
                    }
                
            

All the timestamps returned from the API are given in the timezone UTC-0 (Zulu-time). Time series with resolutiontime day, is timestamped with 11:00Z. The data for a day observation is calculted using "Norwegian normal time" UTC-1. In the response header the serieVersionNo is showing what version for the series that is used for the result. The method is showing the aggregation method used for aggregation for this parameter type. The quality types is indicating if the observed values is be quality checked. The correction types is indicating if the value has been corrected
Example url

https://hydapi.nve.no/api/v1/Observations?StationId=6.10.0&Parameter=1000&ResolutionTime=0

Observations - POST-method

It is also possible to use a POST-method request if you want to fetch several independent time series. In the POST-method you can specify all parameters for each individual time series. Example: I want to get the latest daily(1440) stage-parameter (1000) for Urula-station (12.209.0), the latest hourly(60) water-temperature (1003) for the Lierelv station (1.200.0) and the latest instantenous (0) air-temperature (17) for the Engsetvatn station (101.1.0). This query is not possible with the GET-method in a single request.
The body of the request must be populated this JSON-array:

                
                    [
                        {
                            "stationId": "12.209.0",
                            "parameter": "1000",
                            "resolutionTime": "1440"
                        },
                        {
                            "stationId": "1.200.0",
                            "parameter": "1003",
                            "resolutionTime": "60"
                        },
                        {
                            "stationId": "101.1.0",
                            "parameter": "17",
                            "resolutionTime": "0"
                        }
                    ]
                                
            
Another example: Getting the first week of the year for the stage-parameter (1000) for the three first years in the millennium for station 12.209.0.
            
                    [
                     {
                        "stationId": "12.209.0",
                        "parameter": "1000",
                        "resolutionTime": "1440",
                        "referenceTime": "2000-01-01/P7D"
                     },
                     {
                        "stationId": "12.209.0",
                        "parameter": "1000",
                        "resolutionTime": "1440",
                        "referenceTime": "2001-01-01/P7D"
                     },
                     {
                        "stationId": "12.209.0",
                        "parameter": "1000",
                        "resolutionTime": "1440",
                        "referenceTime": "2002-01-01/P7D"
                     }
                    ]
                
            

Changelog

v1.0

v0.9 (removed version)