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
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.
The API is currently version 1.0, and may be subject to change
without any change in version number.
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.
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",
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: 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 for different languages is available in this GitHub repo.
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.
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
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
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
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
{
"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-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 can be retrieved using a GET-method.
The observations for a series can be found if the following fields are given;
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
}
]
}
]
}
https://hydapi.nve.no/api/v1/Observations?StationId=6.10.0&Parameter=1000&ResolutionTime=0
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"
}
]