NRFA API

Introduction

This page describes the web interface for direct access to river flow data from the UK National River Flow Archive (NRFA). It is designed primarily for programmers (API stands for Application Programming Interface), to enable rapid access to large numbers of datasets. All of the data provided can also be manually downloaded, through a set of user-friendly web-pages, via the NRFA website, including an easy to use map-based search page. We recommend that non-programmers access NRFA data in this way.

This is a test service to help us to understand user needs. It is possible that the services provided, including url patterns, parameters, and formats of data returned, will change prior to release of an operational service. Once the operational service is released we will endeavour to ensure changes are managed in a way to assist continuity of use.

By using this NRFA API you are agreeing to the terms and conditions of use. See Terms and conditions of use / Licence below.

The following acknowledgement shall, unless otherwise stated, be used on all copies of the Data, publications and reports, including but not limited to, use in presentations to any audience.

Acknowledgement: Data from the UK National River Flow Archive

Background
Terms and conditions of use
Access and restrictions
HTTP URL pattern
Web-services
Web-service: station-ids
Web-service: station-info
Web-service: time-series
Time-series CSV format
Time-series JSON format
Time-series FEH formats
A working example
Query string parameters
Parameter: station
Parameter: data-type
Parameter: format
Tabular data formats
Time-series data formats
Parameter: pipe
Parameter: flags
Parameter: dates
Parameter: encoding
Parameter: callback
HTTP requests and responses
HTTP request headers
HTTP response headers
HTTP status codes

Background

The NRFA is the UK's focal point for river flow data. We collate, quality control and archive hydrometric data from gauging station networks across the UK including the extensive networks operated by the Environment Agency (England), Natural Resources Wales, the Scottish Environment Protection Agency and the Department for Infrastructure - Rivers. For information on the work of the NRFA, see our website.

This API provides access to NRFA river flow gauging station information, including station metadata (the type of station, its location and key characteristics), information about the station's catchment (land use, geology, climate, etc.), and time series of daily river flows measured at the station.

Please see here for information about the NRFA Data Update Schedule.

Terms and conditions of use / Licence

By using this service you are agreeing to conform to the NRFA API licence, covering use of the data and the API. The licence can be found here:

NRFA Data Terms and Conditions for access to time-series data and metadata

Access and restrictions

Currently there are no controls or restrictions in using this API, but this may not always be the case.

HTTP URL pattern

Calls to the NRFA API should follow this basic pattern:

https://nrfaapps.ceh.ac.uk/nrfa/ws/web-service[/path]?query-string

where:

https://nrfaapps.ceh.ac.uk/nrfa/ws
is the root entry point of the API. For code that calls the NRFA API it is recommended that this string be put into a variable. This location may change in the future.
web-service
is the name of the web-service that you wish to call. See Web-services below for a full list of available web-services.
[/path]
is an optional path element that can be appended to the web-service. If specified then this is generally used to set the file name used to store the returned data.
?query-string
contains parameter name/value pairs that provide additional options for the web-service.

Note: Some characters are utilised by URLs for special use in defining their syntax. The forward slash / and colon : characters are examples of such special characters. When these special characters are not used in their special role inside a URL, they must be encoded.

Web-services

station-idsReturn a list of all NRFA station identifiers.
station-infoReturn station metadata for one or more NRFA stations.
time-seriesReturn time-series data for a single station and data-type.

Web-service: station-ids

https://nrfaapps.ceh.ac.uk/nrfa/ws/station-ids[/path]?query-string

Returns a list of NRFA station identifiers. These station identifiers can then be used as values for the station parameter of other web-services to return data for that particular station.

Required parameters:

Optional parameters:

Example

Retrieve a list of all station identifiers in a JSON object:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-ids?format=json-object
Retrieve a list of all station identifiers as an HTML document:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-ids?format=html
Retrieve a list of all station identifiers as an HTML document:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-ids/nrfa-stations.html
A path is specified, which indicates HTML output so the format parameter is not needed.

Web-service: station-info

https://nrfaapps.ceh.ac.uk/nrfa/ws/station-info[/path]?query-string

Returns one or more items of metadata for one or more NRFA stations.

Required parameters:

Optional parameters:

The fields parameter consists of a comma separated list of codes that determine the station metadata that is to be returned:

fields=code,code,...

id
The station identifier.
name
The station name.
default
Both the id and name fields.
catchment-area
The catchment area (in km2).
grid-reference
The station grid reference. For JSON output the grid-reference is represented as an object with the following properties:
ngr
(String) The grid reference in string form (i.e. SS9360201602).
easting
(Number) The grid reference easting (in metres).
northing
(Number) The grid reference northing (in metres).
lat-long
The station latitude/longitude. For JSON output the lat-long is represented as an object with the following properties:
string
(String) The textual representation of the lat/long (i.e. 50°48'15.0265"N 3°30'40.7121"W).
latitude
(Number) The latitude (expressed in decimal degrees).
longitude
(Number) The longitude (expressed in decimal degrees).
river
The name of the river.
location
The name of the location on the river.
station-level
The altitude of the station, in metres, above Ordnance Datum or, in Northern Ireland, Malin Head.
easting
The grid reference easting.
northing
The grid reference northing.
station-information
Basic station information: id, name, catchment-area, grid-reference, lat-long, river, location, station-level, measuring-authority-id, measuring-authority-station-id, hydrometric-area, opened, closed, station-type, bankfull-flow, structurefull-flow, sensitivity.
category
Information about the main station categories: nrfa-mean-flow, nrfa-peak-flow, feh-pooling, feh-qmed, feh-neither, nhmp, benchmark, live-data.
catchment-information
Basic catchment information: factors-affecting-runoff.
gdf-statistics
Gauged daily flow statistics: gdf-start-date, gdf-end-date, gdf-mean-flow, gdf-min-flow, gdf-first-date-of-min, gdf-last-date-of-min, gdf-max-flow, gdf-first-date-of-max, gdf-last-date-of-max, gdf-q95-flow, gdf-q70-flow, gdf-q50-flow, gdf-q10-flow, gdf-q05-flow, gdf-base-flow-index, gdf-day-count, gdf-flow-count.
peak-flow-statistics
Basic peak-flow statistics: peak-flow-start-date, peak-flow-end-date, qmed.
elevation
Catchment elevation pecentile data: minimum-altitude, 10-percentile-altitude, 50-percentile-altitude, 90-percentile-altitude, maximum-altitude.
catchment-rainfall
Catchment rainfall standard period data: saar-1941-1970, saar-1961-1990.
lcm2000
Land cover map data (2000): lcm2000-woodland, lcm2000-arable-horticultural, lcm2000-grassland, lcm2000-mountain-heath-bog, lcm2000-urban.
lcm2007
Land cover map data (2007): lcm2007-woodland, lcm2007-arable-horticultural, lcm2007-grassland, lcm2007-mountain-heath-bog, lcm2007-urban.
geology
Catchment geology data: high-perm-bedrock, moderate-perm-bedrock, low-perm-bedrock, mixed-perm-bedrock, high-perm-superficial, low-perm-superficial, mixed-perm-superficial.
feh-descriptors
FEH catchment descriptors: propwet, bfihost, farl, dpsbar.
urban-extent
Urban extent data: urbext-1990, urbext-2000.
spatial-location
The grid reference and lat/long as individual fields: easting, northing, latitude, longitude.
peak-flow-metadata
Metadata related to peak-flow data: peak-flow-rejected-amax-years, peak-flow-rejected-periods.
all
Everything.

Examples

Return the default station information for station 43009 as a JSON object:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-info?station=43009&format=json-object
Return station location information for station 43009:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-info?station=43009&format=json-object&fields=id,name,grid-reference,lat-long
Return various station metadata for three stations in CSV format:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-info?station=15006,39001,28022&format=csv&fields=id,name,grid-reference,catchment-area
Return everything for all stations as an HTML document:
https://nrfaapps.ceh.ac.uk/nrfa/ws/station-info?station=*&format=html&fields=all

Web-service: time-series

This web-service is used to retrieve time-series data.

Required parameters:

Optional parameters:

Time-series CSV format

When the format parameter is specified as nrfa-csv the time-series data is returned in traditional NRFA CSV format. This is the same format that is returned when using the Download flow data button on the Daily Flow Data tab of a station page.

Time-series JSON format

The returned object has the following properties:

timestamp
An ISO 8601 format string containing the date and time that this output was created.
interval
An ISO 8601 repeating interval format string indicating the date/time range and period of the returned data. This string is in the format Rsize/start/period where:
period
Is an ISO 8601 duration string containing the period of the data in the time-series. For a daily time-series this will be P1D and for a monthly time-series this will be P1M. For fifteen-minute sub-daily data this will be PT15M.
size
The total size of the time-series data. This is the total number of period units between the start and end of the time-series. For example, for a daily time-series this is the number of days between the start and end of the series. For sparse time-series data-types, such as pot-flow and pot-stage, the number of values in the time-series will be considerably less than the size.
start
Is an ISO 8601 format string containing the date/time of the first elements in the time-series. The exact format used is related to the period. For daily data where period is P1D the format of start will be yyyy-mm-dd. For monthly data where period is P1M the format of start will be yyyy-mm.
station
An object containing basic metadata describing the station:
id
The station identifier
name
The station name
data-type
An object containing basic metadata describing the data-type of the returned time-series data:
id
The data-type identifier
name
The data-type name
parameter
The parameter being measured. This will generally be either Flow or Stage as appropriate for the data-type.
units
The units. For flow data-types the units are m3/s and for stage data-types the units are m.
measurement-type
Some additional information describing how the parameter is measured.
data-stream
An array containing a list of values that are used to build the time-series data. This is not an array in the usual sense; it is a sequence of JSON values that are processed one after the other to build the time-series dataset.

The values in the array can have the following JSON types:

string
An ISO 8601 format date/time to which the next value applies.
number
The next value in the time-series.
array
The next value in the time-series, along with some flag information, that applies to that value. The array has two elements:
  1. A number. The next value in the time-series.
  2. A string containing some flag information that applies to the value.

Code that reads the values in the data-stream property will use a date/time cursor to build up the time-series. String date/time values are used to set the position of the cursor, and number values set the value at the cursor position and advance the cursor to the next date/time position. By default, every time-series value is preceded by the date/time on which it occurs. If the dates=false parameter is specified (see here) then only the starting date/time of a sequential block of data is returned. The date/time values within the block can be calculated by the code reading the data. The Working example below incorporates JavaScript code (here) that processes the data-stream array.

Note: All NRFA time-series date/time values are in UTC.

Time-series FEH formats

When the format parameter is specified as feh-data the time-series data is returned in FEH data format. This is the format used for the .AM and .PT files contained in the NRFA Peak Flow Dataset. This format is only valid for AMAX and POT data-types (amax-stage, amax-flow, pot-stage and pot-flow).

When the format parameter is specified as feh-csv the time-series data is returned in FEH CSV format. This is the format used for the .CSV files contained in the Peak-flow data release Zip files. This format is only valid for POT data-types (pot-stage and pot-flow).

The pipe parameter is ignored when either the feh-data or feh-csv format is specified.

Examples

Return Catchment Daily Rainfall data for station 45001 as a CSV file:
https://nrfaapps.ceh.ac.uk/nrfa/ws/time-series?format=nrfa-csv&data-type=cdr&station=45001
Return Catchment Monthly Rainfall data for station 45001 as a JSON object:
https://nrfaapps.ceh.ac.uk/nrfa/ws/time-series?format=json-object&data-type=cmr&station=45001
Return annual totals for complete years of Catchment Monthly Rainfall data for station 45001 as a JSON object:
https://nrfaapps.ceh.ac.uk/nrfa/ws/time-series?format=json-object&data-type=cmr&station=45001&pipe=aggregate%3Asum%3Ap1y%3Am0
Return AMAX data for station 45001 in FEH .AM format:
https://nrfaapps.ceh.ac.uk/nrfa/ws/time-series/045001.am?format=feh-data&data-type=amax-stage&station=45001
NB. You can specify the data-type as either amax-stage or amax-flow and the result will be the same (the file contains both stage and flow values).

A working example

The following link points to an example web application that uses the NRFA API and an external charting library to produce simple interactive time-series plots.
https://nrfaapps.ceh.ac.uk/nrfa/api-example-01

Query string parameters

The query string of the URL consists of a set of parameter name/value pairs. There are standard parameters that are common to all web-services:

Parameter: station

Specifies one or more NRFA stations.

station=station-id
A single NRFA station with the station identifier station-id.
station=station-id,station-id,...
Multiple NRFA stations using a comma separated list of station identifiers.
*
All NRFA station identifiers.

Depending on the context in which the station parameter is used one or more of the formats decribed above may not be legal (i.e. a web-service might allow only a single station to be specified).

Parameter: data-type

Specifies one or more time-series data-types.

data-type=dt
A single NRFA time-series data-type.
data-type=dt,dt,...
Multiple NRFA time-series data-types using a comma separated list.

Depending on the context in which the data-type parameter is used one or more of the formats decribed above may not be legal (i.e. a web-service might allow only a single data-type to be specified).

The following data-types are available:

gdf
Gauged daily flows
ndf
Naturalised daily flows
gmf
Gauged monthly flows
nmf
Naturalised monthly flows
cdr
Catchment daily rainfall
cdr-d
Catchment daily rainfall distance to rain gauge
cmr
Catchment monthly rainfall
pot-stage
Peaks over threshold stage
pot-flow
Peaks over threshold flow
gauging-stage
Gauging stage
gauging-flow
Gauging flow
amax-stage
Annual maxima stage
amax-flow
Annual maxima flow

Parameter: format

Specifies the format of the returned data.

Tabular data formats

For web-services returning tabular data the following values can be specified for the format parameter:

csv
Data is returned in comma separated value format. The Content-Type header of the HTTP response is set to text/csv.
html
Data is returned in HTML format. The Content-Type header of the HTTP response is set to text/html.
json-array
Data is returned in JSON format as an array.
json-object
Data is returned in JSON format as an object.

For both the json-array and json-object formats the Content-Type header of the HTTP response is set to either application/json or application/javascript depending on whether the callback parameter has been specified.

Time-series data formats

For web-services returning time-series data the following values can be specified for the format parameter:

json-object
Data is returned in JSON format as an object.
nrfa-csv
Data is returned in traditional NRFA CSV format.
feh-data
Data is returned in FEH data format.
feh-csv
Data is returned in FEH CSV format.

Parameter: pipe

Specifies one or more pipe-line stages to be applied to a time-series data-set. The pipe parameter can only be specified for the time-series web-service.

pipe=pipe-spec
A sequence of pipe-line stages, separated by the vertical-bar | character.

The following pipe-line stages are currently supported:

lower-envelope
Calculate the lower envelope of the time-series data.
upper-envelope
Calculate the upper envelope of the time-series data.
aggregate:function:period[:missing-criteria]
Apply an aggregation function to the time-series data. There are three elements that control how the function is applied to the time-series data:
  1. The aggregation function. The following functions are supported:
    • count
    • sum
    • mean
    • min
    • max
    • p5
    • p95
    • pn
  2. The period over which the function is to be applied. The period is specified as an ISO 8601 duration format string. Typical values include:
    • p1d   A calendar day.
    • p1m   A calendar month.
    • p1y   A calendar year.
  3. Missing data requirements.
    • -   Generate an output value whenever possible, regardless of the completeness of the input data.
    • mn   Calculate a value only if there are no more than n values missing in the period.
    • pn   Calculate a value only if there are at least n input values in the period.
    • n%   Calculate a value only if the data in the period is at least n percent complete.

Note: Both the vertical-bar | character and the colon : character should be escaped to ensure that the URL is processed correctly.

Parameter: flags

Specifies whether time-series flags are to be returned. The flags parameter can only be specified for the time-series web-service and only when the format is set to json-object.

flags=boolean
The value of boolean must be either true or false.
false
Default value. Do not output any flag information.
true
If value is flagged as estimated or suspect then write out the value as a JSON array [value,flag] else just write out value.

Parameter: dates

Specifies when the date/time of a time-series value is to be output. The dates parameter can only be specified for the time-series web-service and only when the format is set to json-object.

dates=boolean
The value of boolean must be either true or false.
false
Write the date/time before only the first value of a sequence of time-series values. The date/time for subsequent values in the sequence can be calculated from the position of the value in the sequence. Specifying dates=false can significantly reduce the download size for certain data-types.
true
Default value. Write the date/time before every value in the time-series.

Parameter: encoding

Specifies the character set encoding to be used for text output. If encoding is not specified then character data is encoded using the utf-8 encoding. Other possible encodings include utf-16, utf-16be, utf-16le, utf-32, utf-32be, utf-32le and us-ascii. If the output format is not character based then this parameter is ignored.

Parameter: callback

This parameter is used when you wish to return data in JSONP format rather than JSON format. It is ignored if the output format is not JSON. To specify JSON format output set the format parameter to either json-array or json-object. The value of the callback parameter is the name of the JavaScript function to be called.

HTTP requests and responses

HTTP request headers

The following headers may be set in the HTTP request:

Accept-Encoding
The NRFA API supports gzip and deflate encoding, as well as the identity encoding. It is recommended that the gzip encoding be used where possible to reduce network traffic.

HTTP response headers

The following headers are set in the HTTP response:

Access-Control-Allow-Origin
This header allows cross-domain requests to the NRFA API.
Content-Encoding
As appropriate.
Cache-Control
As appropriate for the particular web-service and the data that it is returning.
Content-Disposition
Optionally set as appropriate for the output format.
Content-Type
As appropriate for the web-service and the output format.

HTTP status codes

200 - OK
If the web-service executed without any errors.
400 - Bad Request
One or more of the inputs is illegal.
404 - Not Found
The web-service does not exist.
500 - Internal Server Error
Ordinarily this error should not occur. It indicates a more fundamental problem with the web server.

If the status code indicates an error (i.e. is anything other than 200) then the Content-Type is set to text/html and the response contains HTML that will hopefully provide more details about what went wrong.