beta This is a trial service – your feedback will help us to improve it.

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)

For questions on the APIs please contact data.info@environment-agency.gov.uk, a forum for announcements and discussion is under consideration.

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, see below for details. In the links in the tables {root} corresponds to http://environment.data.gov.uk/flood-monitoring.

Real time rainfall measurements

WhatAPIFilters
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, search=x (text in label)
All readings for all measures from across all the stations: {root}/data/readings?parameter=rainfall latest, today, date=d, startdate=d1&enddate=d2, since=dt, 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:

SuffixType
.jsonapplication/json
.ttltext/turtle
.rdfapplication/rdf+xml
.htmltext/html
.csvtext/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 below.

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:

QueryMeaning
?_view=fullReturn a full description of each item in the list, instead of the default minimal description. Only relevant for some endpoints.
?_limit=xReturn 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=xReturn 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:

QueryMeaning
?label=xReturn only those stations whose label is exactly x.
?stationReference=xReturn only those stations whose reference identifier is x. The station reference is an internal identifier used by the Environment Agency.
?RLOIid=rReturn only the station (if there is one) whose RLOIid (River Levels on the Internet identifier) matches r.
?search=xReturn only those stations whose label contains x
?lat=y&long=x&dist=dreturn 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

FieldMeaningTypeOccurs
measuresThe set of measurement types available from the stationrt:Measuremulti-valued
notationA string or other literal which uniquely identifies the item.xsd:string
stationReferenceIdentifier for the telemetry feed used by the Environment Agency's National Flood Forecasting Systemstring
lat Latitude of the station, in WGS84 coordinate ref, rounded to 100m grid xsd:decimaloptional
long Longitude of the station, in WGS84 coordinate ref, rounded to 100m grid xsd:decimaloptional
easting Easting of the station on British National Grid, rounded to 100m grid xsd:integeroptional
northing Northing of the station on British National Grid, rounded to 100m grid xsd:integeroptional
gridReference Grid reference for station, rounded to 100m grid xsd:stringoptional
type A list of types for the station, will be rt:Station. owl:Classoptional

Structure of nested field measures:

FieldMeaningTypeOccurs
parameterShort, canonical, name of the quantity being measured - "rainfall".string
parameterNameThe name of the quantity being measured - "Rainfall".string
periodThe period between successive readings, in seconds.xsd:decimal
qualifierA qualifier for the quantity being measured - "Tipping Bucket Raingauge".string
unitNameA 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:

QueryMeaning
?parameterName=xReturn only measures for parameters with the given name x, for example Water Level or Rainfall.
?parameter=xReturn only measures for parameters with the given short form name x, for example level or rainfall.
?qualifier=xReturn only those measures with qualifier x.
?stationReference=xReturn only those measures which are available from the station with the reference identifier x.
?station=xReturn only those measures which are available from the station with the URI x.
?search=xReturn only those measures whose label contains x

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

Returned data

FieldMeaningTypeOccurs
datumTypeFor 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
labelA name for the itemxsd:string
latestReadinglinks from a measure the latest available readingrt:Readingoptional
notationA string or other literal which uniquely identifies the item.xsd:string
parameterShort, cannonical, name of the quantity being measured e.g. "level", "flow" or "temperature".string
parameterNameThe name of the quantity being measured e.g. "Water Level", "Flow", "Temperature"string
periodThe period between successive readings, in seconds.xsd:decimaloptional
qualifierA 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
stationThe URI of the monitoring station supplying the measurerdfs:Resource
stationReferenceIdentifier for the telemetry feed used by the Environment Agency's National Flood Forecasting Systemstring
unitThe units in which this parameter is measured, e.g. qudt:Meteroptional
unitNameA name for the units for this measurement including the datumType. Typical values are mAOD (for meters relative to the Ordnance Survey datum), mASD (for meters relative to the local stage datum), m (for meters with an unspecified datum) and m3/s (for flow rates).xsd:stringoptional
valueTypeIndicates whether the measured value is an instantaneous reading or a total, mean or maximum over the period.optional

Structure of nested field latestReading:

FieldMeaningTypeOccurs
dateThe date at which the reading occurredxsd:date
dateTimeThe date time at which the reading occurredxsd:dateTime
measureThe URI of the measure being recorded in this reading, this define the location (station), the parameter being measured and other qualifying information.rt:Measure
valueThe 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:

QueryMeaning
?latestReturn only the most recently available reading for each included measure.
?todayReturn all the readings taken today for each included measure.
?date=2015-02-05Return all the readings taken on the specified day for each included measure.
?startdate=2015-02-05&enddate=2015-02-07Return the readings taken on the specified range of days for each included measure, up to the specified _limit. If no _limit is given then a default limit of 500 will be used.
?since=2016-09-07T10:30:00ZReturn the readings taken since the given date time (not inclusive), up to the specified _limit. If no _limit is given then a default limit of 500 will be used. 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:

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

Other modifiers:

QueryMeaning
?_view=fullReturn an inline description of the measure to which the reading applies.
?_sortedOrder 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

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

Returned data

FieldMeaningTypeOccurs
dateThe date at which the reading occurredxsd:date
dateTimeThe date time at which the reading occurredxsd:dateTime
measureThe URI of the measure being recorded in this reading, this define the location (station), the parameter being measured and other qualifying information.rt:Measure
valueThe 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:

FieldMeaningTypeOccurs
datumTypeFor 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
parameterShort, cannonical, name of the quantity being measured e.g. "level", "flow" or "temperature".string
periodThe period between successive readings, in seconds.xsd:decimaloptional
qualifierA 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
stationThe URI of the monitoring station supplying the measurerdfs:Resource
stationReferenceIdentifier for the telemetry feed used by the Environment Agency's National Flood Forecasting Systemstring
unitNameA name for the units for this measurement including the datumType. Typical values are mAOD (for meters relative to the Ordnance Survey datum), mASD (for meters relative to the local stage datum), m (for meters with an unspecified datum) and m3/s (for flow rates).xsd:stringoptional
valueTypeIndicates whether the measured value is an instantaneous reading or a total, mean or maximum over the period.optional

Structure of nested field station:

FieldMeaningTypeOccurs
labelA name for the itemxsd: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.