Environment Agency Rainfall API

Introduction

The Environment Agency has approximately 1000 real time rain gauges which are connected by telemetry. Measurements of the amount of precipitation (mm) are captured in Tipping Bucket Raingauges (TBR). The data reported here gives accumulated totals for each 15 min period. The data is typically transfered once or twice per day.

The Rainfall API provides access to these rainfall measurements, and to information on the monitoring stations providing those measurements. It is compatible with (and integrated into) the API for water level/flow readings.

Note that for information protection reasons the rainfall monitoring stations do not have names and their geographic location has been reduced to a 100m grid.

These APIs are provided as open data under the Open Government Licence with no requirement for registration. If you make use of this data please acknowledge this with the following attribution statement:

this uses Environment Agency rainfall data from the real-time data API (Beta)

Demonstration application

A demonstration single-page web application that illustrates how to use the API is hosted at Rainfall API demonstrator with source code available from github.

Recent updates

Version 0.7: Rainfall data added to real time data API.

API summary

This is a brief summary of the APIs available. In the links in the tables {root} corresponds to http://environment.data.gov.uk/flood-monitoring.

Real time rainfall measurements

What	API	Filters
All rainfall measurement stations:	{root}/id/stations?parameter=rainfall	qualifier=q, RLOIid=r, lat=y&long=x&dist=r, search=x (text in label), type=t
All measures available from a particular station	{root}/id/stations/{id}/measures
Information on from a particular station	{root}/id/stations/{id}
All measures from across all the stations:	{root}/id/measures?parameter=rainfall	qualifier=q, stationReference=id, station=uri
All readings for all measures from across all the stations:	{root}/data/readings?parameter=rainfall	latest, today, date=d, startdate=d1&enddate=d2, qualifier=q, stationReference=id, station=uri, _view=full, _sorted
All readings for a particular measure:	{root}/id/measures/{id}/readings	latest, today, date=d, startdate=d1&enddate=d2, since=dt, _view=full, _sorted
All readings for measures from a particular station:	{root}/id/stations/{id}/readings	latest, today, date=d, startdate=d1&enddate=d2, since=dt, _view=full, _sorted

API structure

The APIs provide a REST style access to the data via simple HTTP GET requests which return data in JSON format. Some data is also available in other formats.

Simple requests

For example fetching data from: http://environment.data.gov.uk/flood-monitoring/id/floods

will return a JSON data packet such as:

{
  "@context": "http://environment.data.gov.uk/flood-monitoring/meta/context.jsonld",
  "meta": {
    "publisher": "Environment Agency",
    "licence": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "documentation": "http://environment.data.gov.uk/flood-monitoring/doc/reference",
    "version": "0.7",
    "comment": "Status: Beta service",
    "hasFormat": [
      "http://environment.data.gov.uk/flood-monitoring/id/stations/3680.rdf",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/3680.ttl",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/3680.html"
    ]
  },
  "items": {
    "@id": "http://environment.data.gov.uk/flood-monitoring/id/stations/3680",
    "eaRegionName": "Midland",
    "easting": 467900,
    "gridReference": "SK679153",
    "label": "Rainfall station",
    ...
  }
}

The returned JSON data from all API endpoints follows the same structure of three elements: context, metadata and item(s).

The @context reference is provided to enable the JSON data to be read as json-ld.

Metadata and versioning

The metadata block:

"meta" : {
    "publisher": "Environment Agency",
    "licence": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "documentation": "http://environment.data.gov.uk/flood-monitoring/doc/reference",
    "version": "0.7",
    "comment": "Status: Beta service",
    "hasFormat": [
      "http://environment.data.gov.uk/flood-monitoring/id/stations/3680.rdf",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/3680.ttl",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/3680.html"
    ]
  }

provides information on the publisher and applicable licence as well as a link to this, or other, documentation. If the resource is also available in other formats then hasFormat will supply list of URLs for those alternative formats (the media type is implied a suffix, see content types).

The metadata block also includes version number information. The intention is that updates to the API should maintain backward compatibility. If an incompatible change to the API is required then we will attempt to provide access to the prior version for a transitional period. In that case the meta block will also provide replaces and isReplacedBy links between the new and the old versions of the affected API endpoints.

Fininally, in the case of calls which provide lists of results then any applied limit to the length of the list and offset from the start of the list will be shown in the metadata as limit and offset values, for example:

"meta" : {
    "publisher" : "Environment Agency" ,
    "licence" : "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" ,
    "documentation" : "http://environment.data.gov.uk/flood-monitoring/doc/reference" ,
    "version": "0.7",
    "comment": "Status: Beta service",
    "limit" : 10,
    "offset" : 5
  }

Note that some endpoints impose a length limit even if one has not be specified explicitly by the caller. The metadata is particularly useful in this case as a warning that this has occurred.

Items

The items element in the JSON response will contain either a description of a single item or an array of items. For API endpoints which return lists of items (e.g. all measurement stations of a certain kind) the value will always be an array even if the list only has one entry. For API endpoints which describe a specific item (e.g. a particular measurement station) the value will always be an object, with no wrapping array.

Each item will normally be identified by a URI given in the @id field. Thus, for example in the fuller version of the earlier example:

 "items": {
  "@id": "http://environment.data.gov.uk/flood-monitoring/id/stations/3680",
  "eaRegionName": "Midland",
  "easting": 467900,
  "gridReference": "SK679153",
  "label": "Rainfall station",
  "lat": 52.73,
  "long": -0.996,
  "measures": [
    {
      "@id": "http://environment.data.gov.uk/flood-monitoring/id/measures/3680-rainfall-tipping_bucket_raingauge-t-15_min-mm",
      "label": "rainfall-tipping_bucket_raingauge-t-15_min-mm",
      "latestReading": {
        "@id": "http://environment.data.gov.uk/flood-monitoring/data/readings/3680-rainfall-tipping_bucket_raingauge-t-15_min-mm/2016-09-07T04-00-00Z",
        "date": "2016-09-07",
        "dateTime": "2016-09-07T04:00:00Z",
        "measure": "http://environment.data.gov.uk/flood-monitoring/id/measures/3680-rainfall-tipping_bucket_raingauge-t-15_min-mm",
        "value": 0
      },
    "notation": "3680-rainfall-tipping_bucket_raingauge-t-15_min-mm",
    "parameter": "rainfall",
    "parameterName": "Rainfall",
    "period": 900,
    "qualifier": "Tipping Bucket Raingauge",
    "station": "http://environment.data.gov.uk/flood-monitoring/id/stations/3680",
    "stationReference": "3680",
    "type": [
      "http://environment.data.gov.uk/flood-monitoring/def/core/Measure",
      "http://environment.data.gov.uk/flood-monitoring/def/core/Rainfall"
    ],
    "unit": "http://qudt.org/1.1/vocab/unit#Millimeter",
    "unitName": "mm",
    "valueType": "total"
  }, ... ] ... }

we can see that the station has a URI identifier but so does the rainfall measurement and indeed so does an individual reading such as the latest reading from that measurement.

When one item references another, such as in this case, the API will typically include key attributes of the referenced item in-line for convenience. However, we can always fetch (GET) data from the referenced item URI to obtain a full description.

Many of these URIs are stable long term reference identifiers e.g. the measurement stations and the individual measurement types are stable. However, some items may only be transient. For example, the URI for an individual reading will only remain valid for 28 days. After that the data will disappear from the API window and the URI will no longer resolve, returning a 404.

Content Types

The descriptions of individual items can be obtained in multiple formats. The default format is JSON but all item descriptions can also return information in RDF formats (RDF/XML and Turtle). In addition some items offer a simple HTML rendering which makes it possible to look at these reference identifiers conveniently in a browser. The HTML rendering is intended as an aid to help developers understand the data, it is not an end-user application.

Similarly lists of items can be obtained in multiple formats. The default is JSON (in which the items field will contain an array of objects) but they are also typically also available in CSV format.

To select the desired format use standard HTTP content negation. E.g.:

 curl -i -H "Accept: text/turtle" http://environment.data.gov.uk/flood-monitoring/id/stations/3680

All endpoints also support a short cut of appending a type suffix to the URI to force a particular content type. The supported suffixes are:

Suffix	Type
.json	application/json
.ttl	text/turtle
.rdf	application/rdf+xml
.html	text/html
.csv	text/csv

Lists: filtering and paging

Some endpoints return information describing a single identified item but many return information on a list of items. In that case the value of the items field is an array of items. Such list endpoints support query parameters to filter the list to only include some items, for example:

returns a list of all measurement stations but filters the list to only those stations which provide a measurement of a rainfall parameter.

The specific filters available depend on the endpoint and are documented in the following tables.

In addition to filtering then list endpoints support view modification parameters, these are distinguished by starting with an underscore character. The commonly supported modifiers are:

Query	Meaning
?_view=full	Return a full description of each item in the list, instead of the default minimal description. Only relevant for some endpoints.
?_limit=x	Return only x items from the list, some endpoints may impose a default limit and/or a maximum to which the limit can be set.
?_offset=x	Return the list of items starting with the xth item, together with _limit this enables paging through a long set of reults.

If a limit or offset is applicable, whether explicit in the query or implicitly imposed by the API, then the metadata object will include a limit or offset field to show what limits were applie

Stations

The real-time data API provides information on readings of rainfall, water levels and flows taken at a variety of measurement stations. A given station may provide more than one set of measurements, for example, some stations measure both rainfall and air temperature. The API provides metadata on these stations and on the different measures available from each one, as well as the readings themselves.

API

To return the list of all measurement stations that offer a rainfall measurement, or some subset thereof:

Supports the following filter parameters:

Query	Meaning
?label=x	Return only those stations whose label is exactly x.
?stationReference=x	Return only those stations whose reference identifier is x. The station reference is an internal identifier used by the Environment Agency.
?RLOIid=r	Return only the station (if there is one) whose RLOIid (River Levels on the Internet identifier) matches r.
?search=x	Return only those stations whose label contains x
?lat=y&long=x&dist=d	return those stations whose location falls within d km of the given latitude/longitude (in WGS84 coordinates), this may be approximated by a bounding box.d must be a plain integer.

Examples

List all rainfall stations in the vicinity of Portishead:

Returned data

Field	Meaning	Type	Occurs
measures	The set of measurement types available from the station	rt:Measure	multi-valued
notation	A string or other literal which uniquely identifies the item.	xsd:string
stationReference	Identifier for the telemetry feed used by the Environment Agency's National Flood Forecasting System	string
lat	Latitude of the station, in WGS84 coordinate ref, rounded to 100m grid	xsd:decimal	optional
long	Longitude of the station, in WGS84 coordinate ref, rounded to 100m grid	xsd:decimal	optional
easting	Easting of the station on British National Grid, rounded to 100m grid	xsd:integer	optional
northing	Northing of the station on British National Grid, rounded to 100m grid	xsd:integer	optional
gridReference	Grid reference for station, rounded to 100m grid	xsd:string	optional
type	A list of types for the station, will be rt:Station.	owl:Class	optional

Structure of nested field measures:

Field	Meaning	Type	Occurs
parameter	Short, canonical, name of the quantity being measured - "rainfall".	string
parameterName	The name of the quantity being measured - "Rainfall".	string
period	The period between successive readings, in seconds.	xsd:decimal
qualifier	A qualifier for the quantity being measured - "Tipping Bucket Raingauge".	string
unitName	A name for the units for this measurement - "mm".	xsd:string

API for individual stations

Given a URI for an individual station then dereferencing it will return a full description of the station. For convenience the station description is available as a rendered HTML page as well as in JSON and RDF format. For example:

By default, with no .html suffix you will get data in JSON format though you can also force this using:

Or when scripting you can use content negotiation to request a response of media type application/json.

The information returned for an individual station will be the same as that summarized above for the list of stations.

Measures

In additional to listing stations, which includes the information on the measures available from each station, you can list the available measures directly:

Supports the following filter parameters:

Query	Meaning
?parameterName=x	Return only measures for parameters with the given name x, for example Water Level or Rainfall.
?parameter=x	Return only measures for parameters with the given short form name x, for example level or rainfall.
?qualifier=x	Return only those measures with qualifier x.
?stationReference=x	Return only those measures which are available from the station with the reference identifier x.
?station=x	Return only those measures which are available from the station with the URI x.

For convenience the measures available from a station may also be listed using the URI pattern:

Returned data

Field	Meaning	Type	Occurs
datumType	For level measurements this indicates the type of reference point the level is measured from. Can be relative to the Ordnance Survey datum (rt:AOD), to a local stage datum (rt:ASD) or rt:BDAT (below datum?).		optional
label	A name for the item	xsd:string
latestReading	links from a measure the latest available reading	rt:Reading	optional
notation	A string or other literal which uniquely identifies the item.	xsd:string
parameter	Short, cannonical, name of the quantity being measured e.g. "level", "flow" or "temperature".	string
parameterName	The name of the quantity being measured e.g. "Water Level", "Flow", "Temperature"	string
period	The period between successive readings, in seconds.	xsd:decimal	optional
qualifier	A qualilfier for the quantity being measured. Most common use is to separate level measures which occur at the top ("Stage") or bottom ("Downstream Stage") of a sluice or weir. Other relevant qualifiers are "Tidal Level" and "Groundwater".	string
station	The URI of the monitoring station supplying the measure	rdfs:Resource
stationReference	Identifier for the telemetry feed used by the Environment Agency's National Flood Forecasting System	string
unit	The units in which this parameter is measured, e.g. qudt:Meter		optional
unitName	A name for the units for this measurement including the datumType. Typical values are mAOD (for metres relative to the Ordnance Survey datum), mASD (for metres relative to the local stage datum), m (for metres with an unspecified datum) and m3/s (for flow rates).	xsd:string	optional
valueType	Indicates whether the measured value is an instantaneous reading or a total, mean or maximum over the period.		optional

Structure of nested field latestReading:

Field	Meaning	Type	Occurs
date	The date at which the reading occurred	xsd:date
dateTime	The date time at which the reading occurred	xsd:dateTime
measure	The URI of the measure being recorded in this reading, this define the location (station), the parameter being measured and other qualifying information.	rt:Measure
value	The value of the reading for the associated measurement, a double not a decimal since some values are NaN. Note that in JSON output NaN is illegal for a number so in JSON any NaN readings will omit the rt:value.	xsd:double

API for individual measures

Given a URI for an individual measure then dereferencing it will return a full description of the measure. For convenience the measure description is available as a rendered HTML page as well as in JSON and RDF format. For example:

To get the JSON description of the individual measure drop the .html suffix or replace it by .json or use content negotiation as usual.

The format of an individual measure description is just the same as that for the measure lists.

Readings

Readings for each of the published measures are available for the recent period (up to the last four weeks). Longer historic data records may be available separately. Each reading comprises a reference to the measure being read (identified by its URI), a date time stamp for when the reading applies and a numeric value. The set of readings is updated every 15 minutes, but the individual measures may be updated less frequently than this.

API

To list all readings (not very useful without filtering):

To list all readings for a particular measure:

To list all readings from a particular station:

Note: The base segment for readings is data whereas for identifiable things (stations, measures, flood areas) it is id. This is deliberate and based on URI pattern advice from UK goverment, and UKGovLD working groups [1][2].

The set of readings can be filtered by time period and by type of measurement.

Filters for time period:

Query	Meaning
?latest	Return only the most recently available reading for each included measure.
?today	Return all the readings taken today for each included measure.
?date=2015-02-05	Return all the readings taken on the specified day for each included measure.
?startdate=2015-02-05&enddate=2015-02-07	Return the readings taken on the specified range of days for each included measure, up to the specified _limit. If no _limit is given see the following size limits section.

Filters for time period, available for readings for a particular measure or station only:

Query

Meaning

?since=2016-09-07T10:30:00Z

Return the readings taken since the given date time (not inclusive), up to the specified _limit. If no _limit is given see the following size limits section. Typically when tracking a particular measurement then use the dateTime of the last retrieved value as the since parameter to find any new readings. Will accept a simple date value such as 2016-09-07 which will be interpreted as 2016-09-07T:00:00:00Z.

Filters for measurement to include:

Query	Meaning
?parameter=x	Return only readings for measures of parameters with the given short form name x, for example level or rainfall.
?qualifier=x	Return only readings of measures with qualifier x.
?stationReference=x	Return only readings of measures which are available from the station with the reference identifier x.
?station=x	Return only readings of measures which are available from the station with the URI x.

Other modifiers:

Query	Meaning
?_view=full	Return an inline description of the measure to which the reading applies.
?_sorted	Order the array of returned readings into descending order by date, this done before the limits is applied thus enabling you to fetch the most recent n readings.

Examples

Return the latest value for all measurements in CSV format:

Return all readings for a single rainfall measurement since a specific time:

Size limits

By default the readings API endpoints have a limit of 500 items, this can be modified by providing an explicit _limit value up to a hard limit of 10000 items.

This default can be modified depending on the query parameters used. The following table shows the parameters that affect the default, ordered from most important to least.

Parameter	Default limit
measure	none
_sorted	500
date	none
today	none
latest	none

This means that if a query includes the date parameter, but neither the measure parameter or the _sorted parameter then there is no default limit.

Similarly, if a query includes the _sorted parameter, but not the measure parameter then the default is 500.

Returned data

Field	Meaning	Type	Occurs
date	The date at which the reading occurred	xsd:date
dateTime	The date time at which the reading occurred	xsd:dateTime
measure	The URI of the measure being recorded in this reading, this define the location (station), the parameter being measured and other qualifying information.	rt:Measure
value	The value of the reading for the associated measurement, a double not a decimal since some values are NaN. Note that in JSON output NaN is illegal for a number so in JSON any NaN readings will omit the rt:value.	xsd:double

Structure of nested field measure:

Field	Meaning	Type	Occurs
datumType	For level measurements this indicates the type of reference point the level is measured from. Can be relative to the Ordnance Survey datum (rt:AOD), to a local stage datum (rt:ASD) or rt:BDAT (below datum?).		optional
parameter	Short, cannonical, name of the quantity being measured e.g. "level", "flow" or "temperature".	string
period	The period between successive readings, in seconds.	xsd:decimal	optional
qualifier	A qualilfier for the quantity being measured. Most common use is to separate level measures which occur at the top ("Stage") or bottom ("Downstream Stage") of a sluice or weir. Other relevant qualifiers are "Tidal Level" and "Groundwater".	string
station	The URI of the monitoring station supplying the measure	rdfs:Resource
stationReference	Identifier for the telemetry feed used by the Environment Agency's National Flood Forecasting System	string
unitName	A name for the units for this measurement including the datumType. Typical values are mAOD (for metres relative to the Ordnance Survey datum), mASD (for metres relative to the local stage datum), m (for metres with an unspecified datum) and m3/s (for flow rates).	xsd:string	optional
valueType	Indicates whether the measured value is an instantaneous reading or a total, mean or maximum over the period.		optional

Structure of nested field station:

Field	Meaning	Type	Occurs
label	A name for the item	xsd:string

By default the response will not include the date (just the datetime) nor the expanded description of the measure unless an explicit _view=full request is made.

Historic Readings

The measurement readings are archived daily as dump files in CSV format. Both the short form and the _view=full form are available.

The data is available from http://environment.data.gov.uk/flood-monitoring/archive with individual archives being at http://environment.data.gov.uk/flood-monitoring/archive/readings-{full-}{date}.csv.

Acknowledgements

Styling for reference pages and html resource pages based on Bootstrap 3.