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.

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

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:

• format (must be one of the tabular formats)

Optional parameters:

• encoding
• callback

Example

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:

• station
• format (must be one of the tabular formats)

Optional parameters:

• fields
• encoding
• callback

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 km²).

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, eflag, historic-droughts, marius, outlook-analogues, outlook-esp.

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.

data-summary

A summary of available time-series data-types for the station. See here for more information about data-types.

description

Licence information and descriptive text: licence-url, description-summary, description-general, description-station-hydrometry, description-flow-record, description-catchment, description-flow-regime.

all

Everything.

Examples

Web-service: time-series

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

Required parameters:

• station — only a single station may be specified
• data-type — only a single data-type may be specified
• format — must be one of the time-series formats: json-object, nrfa-csv, feh-data or feh-csv

Optional parameters:

• start-date, end-date, date-range
• encoding
• callback
• pipe
• flags
• dates

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, start-date, end-date and date-range parameters are ignored when either the feh-data or feh-csv format is specified.

Examples

A working example

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

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.

Parameters: start-date, end-date, date-range

The start-date, end-date and date-range parameters can be used to limit the returned data to a subset of the entire time-series. If either start-date or end-date is specified then date-range cannot be specified. If date-range is specified then neither start-date nor end-date can be specified.

start-date=start

An ISO 8601 format date/time. The resulting time-series will only include data on or after this date/time.

end-date=end

An ISO 8601 format date/time. The resulting time-series will not include data after this date/time.

date-range=start+end

An ISO 8601 format date/time or an ISO 8601 interval (two ISO 8601 dates separated by the / character). The resulting time-series will only include data within the specified date/time range. For example, date-range=1980 will return data only for calendar year 1980, and date-range=1980/1989 will return only data between calendar years 1980 and 1989.

The start-date, end-date and date-range parameters are ignored when either the feh-data or feh-csv format is specified.

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.

date-range:start[:end]

Exclude data outside the specified date range. Both start and end are ISO 8601 format date strings. Only data between the start of start and the end of end (or the end of start if end is not specified) is passed through to the next pipeline stage. For example, specify date-range:yyyy to include only data within calendar year yyyy.

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.