Environment Agency Real Time flood-monitoring API

Introduction

The Environment Agency flood-monitoring API provides developers with access to near real time information covering:

• flood warnings and flood alerts
• flood areas which to which warnings or alerts apply
• measurements of water levels and flows
• information on the monitoring stations providing those measurements

Water levels and flows are regularly monitored, usually every 15 minutes. However, data is transferred back to the Environment Agency at various frequencies, usually depending on the site and level of flood risk. Transfer of data is typically once or twice per day, but usually increases during times of heightened flood risk.

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 flood and river level data from the real-time data API (Beta)

Note on crawling

A common requirement is for an application to maintain a copy of all the latest level/flow values from some (or all) of the measurement stations. The efficient way to do this is to issue a single call every 15 mins:

https://environment.data.gov.uk/flood-monitoring/data/readings?latest

This will retrieve the latest value for all measurements - from which you can pick the ones you are interested. Since the data changes at most every 15 mins then this single call four times an hour will ensure a complete track of all of the data.

This is much preferable to crawling all the stations every 15 mins picking up a single latest value for each station one at a time.

However, this is not sufficient to maintain a complete historical trace since readings are sometimes updated batches. For that purpose a query for the relevant station readings using the since filter is appropriate.

Availability and resilience

While they are intended to be stable and robust the open data APIs do not offer a guarantee of service level and should not be relied upon for safety critical applications. They do not replace the existing channels by which the Agency notifies members of the public and partner organizations of floods and flood risk.

Redirects. At times of high load or in future versions of this API the service may redirect to an alternative URL. Client code should be written so as to follow standard HTTP redirects.

Caching. API responses may be cached for a short period within the serving infrastructure or a content delivery network. At times of high load then limiting API use to common patterns (avoiding custom filtering) will improve the chances of cache hits and so good response times. These common patterns are:

• https://environment.data.gov.uk/flood-monitoring/id/floods
• https://environment.data.gov.uk/flood-monitoring/id/floods?min-severity={x}
• https://environment.data.gov.uk/flood-monitoring/id/3dayforecast
• https://environment.data.gov.uk/flood-monitoring/id/3dayforecast/image/{day}
• https://environment.data.gov.uk/flood-monitoring/data/readings?latest

Recent updates

Version 0.8: Added access to Rainfall data.

Version 0.7:

• Added fine grain since filter for readings.
• Added _view=full option for listing stations (includes scale information).
• Implemented geo-filter for flood warning areas.
• Added support station status data where available (status, statusReason, statusDate).
• Added support for Last-Modified headers and If-Modified-Since requests
• Added html view options for APIs that return lists of results.
• Improved detection of bad API requests.
• Changes to underlying platform may affect the order of columns in CSV results but not the columns themselves.

Version 0.6.1: Enabled filters for station type and status.

Version 0.6: Added support CSV format out for listing stations. Include lat/long and easting/northing in stations listing.

API summary

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

Flood warnings

Real time measurements

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: https://environment.data.gov.uk/flood-monitoring/id/floods

will return a JSON data packet such as:

{
  "@context" : "http://environment.data.gov.uk/flood-monitoring/doc/context-TBD.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.4",
    "comment": "WARNING: Alpha test service, may not be stable",
    "hasFormat": [
        "http://localhost:8080/api/id/floods/91436.rdf",
        "http://localhost:8080/api/id/floods/91436.ttl"
    ]
  },
  "items" : [ {
    "@id" : "http://environment.data.gov.uk/flood-monitoring/id/floods/91436" ,
    "description" : "North Sea Coast from Whitby to Filey" ,
    "eaAreaName" : "Yorkshire" ,
    "eaRegionName" : "North East" ,
    "floodArea" : { ... } ,
    "floodAreaID" : "122WAC953" ,
    "isTidal" : true ,
    "severity" : "Warning no longer in force" ,
    "severityLevel" : 4 ,
    "timeMessageChanged" : "2015-02-02T19:32:00" ,
    "timeRaised" : "2015-02-02T19:32:00" ,
    "timeSeverityChanged" : "2015-02-02T19:32:00"
  } , ... ]
}

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.4",
    "comment": "WARNING: Alpha test service, may not be stable",
    "hasFormat": [
        "http://localhost:8080/api/id/floods/91436.rdf",
        "http://localhost:8080/api/id/floods/91436.ttl"
    ]
  }

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.

Finally, 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.4" ,
    "comment" : "WARNING: Alpha test service, may not be stable" ,
    "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) then 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/floods/91436" ,
    "description" : "North Sea Coast from Whitby to Filey" ,
    "eaAreaName" : "Yorkshire" ,
    "eaRegionName" : "North East" ,
    "floodArea" : {
      "@id" : "http://environment.data.gov.uk/flood-monitoring/id/floodAreas/122WAC953" ,
      "county" : "North Yorkshire" ,
      "notation" : "122WAC953" ,
      "polygon" : "http://environment.data.gov.uk/flood-monitoring/id/floodAreas/122WAC953/polygon" ,
      "riverOrSea" : "North Sea"
    }
     ,
    "floodAreaID" : "122WAC953" ,
    "isTidal" : true ,
    "severity" : "Warning no longer in force" ,
    "severityLevel" : 4 ,
    "timeMessageChanged" : "2015-02-02T19:32:00" ,
    "timeRaised" : "2015-02-02T19:32:00" ,
    "timeSeverityChanged" : "2015-02-02T19:32:00"
  } ... ] 

we can see the flood warning itself has an identifier (note that warnings have a limited lifetime so this URL isn't live any more):

as does the flood area to which the warning applies:

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 reference item URI to obtain a full description. For example, dereferencing the flood area URI returns:

  {
    "@id" : "http://environment.data.gov.uk/flood-monitoring/id/floodAreas/122WAC953" ,
    "county" : "North Yorkshire" ,
    "currentWarning" : { ... } ,
    "description" : "The North Sea coast from Whitby to Filey, including Scarborough" ,
    "eaAreaName" : "Yorkshire" ,
    "eaRegionName" : "North East Region" ,
    "fwdCode" : "122WAC953" ,
    "label" : "North Sea Coast from Whitby to Filey" ,
    "notation" : "122WAC953" ,
    "polygon" : "http://environment.data.gov.uk/flood-monitoring/id/floodAreas/122WAC953/polygon" ,
    "quickDialNumber" : "130401" ,
    "riverOrSea" : "North Sea" ,
    "type" : [ "http://environment.data.gov.uk/flood-monitoring/def/core/FloodAlertArea", "http://environment.data.gov.uk/flood-monitoring/def/core/FloodArea" ]
  }

Many of these URIs are stable long term reference identifiers e.g. the flood areas, the measurement stations and the individual measurement types are stable. However, some items may only be transient. For example, the URI for an individual flood alert may only remain valid for a few days. The severity of the alert, and associated message, may change over that time eventually reducing to severity level 4 (Warning no longer in force). After that the alert will disappear and that 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" https://environment.data.gov.uk/flood-monitoring/id/floodAreas/122WAC953

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:

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 flood alerts and warnings which are of severity 3 of worse.

The specific filters available depend on the endpoint and are documented in the following tables. Though many endpoints will support two common filters:

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:

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 applied.

Flood warnings

The Environment Agency issue warnings of floods that cover specific warning or alert areas. The floods API provides a listing of all current such warnings and is updated every 15 minutes.

A warning may be at one of four possible severity levels:

API

An update to the Flood Warning API took place on 30 June 2020. Although as much as possible has been done to ensure limited knock on effects to end users, please contact us via the feedback links to report any issue. The main change is in the way the @id and URI of the individual flood warning is constructed.

The list of current flood warnings:

Supports the following filter parameter:

So for example, to find all warnings that are currently in effect use:

To find all warnings that apply to areas in Somerset use:

Each individual warning with have a URI given by the @id field in the data:

The {id} section of this URI is taken from the value of the floodAreaID. Therefore the current warning for a flood area (if any warning exists) will always have the same URI.

The severity level and the message field may change through the lifetime of the warning. The data for a warning will include the time at which the severity last changed. At some point after a warning is no longer in force it will disappear from the data feed and the URI for that warning will cease to resolve. If no warning is currently in place for that flood area, then attempting to resolve the URI will return a 404 status code.

For approximately 24 hours after a warning has been in place for a flood area, the severity level will be set to 4, "Warning no Longer in Force", before the warning response is removed altogether.

Returned data

Structure of nested field floodArea:

Flood areas

The flood areas API provide information on the geographic regions to which a given flood alert or warning may apply. These comprise Flood Alert Areas and Flood Warning Areas. A Flood Alert Area is a geographical area where it is possible for flooding to occur from rivers, sea and in some locations, groundwater. A single Flood Alert Area may cover a large portion of the floodplain, may contain multiple river catchments of similar characteristics and may contain a number of Flood Warning Areas. A Flood Warning Area is a geographical area where Environment Agency expect flooding to occur and which they provide a Flood Warning Service.

Full information on the areas is available from the Environment Agency Spatial Data Catalogue as a downloadable file and via a Web Feature Service or Web Mapping Service. For convenience we here provide the feature information for each area as a simple JSON format, including a specification of the polygon for each area (as a geoJSON feature in WGS84 coordinates). A typical application should maintain a local copy of the geographic information rather that reply on on-demand downloads of the rather large polygon files.

Each flood warning provides a link (floodArea) to the URI of the flood area to which it applies.

API

To describe an individual area

To list all flood areas (several thousand):

Supports the following filter parameter:

The default limit on number of returned items is 500, this can be adjusted by given an explicit _limit value, there is no hard upper limit.

Returned data

Stations

The real-time data API provides information on readings of water levels and flows taken at a variety of measurement stations. A given station may provide more than one set of measurements, for example, both water level and flow rate or water level at two different spots (e.g. up-stream and down-stream of a sluice or weir). 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 (several thousand), or some subset thereof:

Supports the following filter parameters:

Examples

List all stations which measure flow rates:

List all stations which measure a downstream level:

List 10 stations in the Costwold catchment:

List all stations whose name includes "River Wey":

List all stations whose "River name" value is "Cherwell":

Returned data

Structure of nested field measures:

Views

In addition to the default view, it is possible to obtain a more complete description of each station in the (filtered) list of stations by using _view=full. This will force the including of stage and downstage scale information (see next sections) when available.

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 is enriched by also including scale information for those stations for which this is available.

In each case the scale information is an object with the following fields:

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:

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

The list of currently available types of measurement are:

Returned data

Structure of nested field latestReading:

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 use a .json suffix or 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:

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

Filters for measurement to include:

Other modifiers:

Examples

Return the latest value for all measurements in CSV format:

Return the latest readings from all groundwater measurements:

Return the latest flow readings:

Return the latest flow readings, with descriptions of the measurements:

Return the most recent 10 readings from the upstream level measurement at King's Mill on the River Cherwell:

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.

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

Structure of nested field measure:

Structure of nested field station:

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 https://environment.data.gov.uk/flood-monitoring/archive with individual archives being at https://environment.data.gov.uk/flood-monitoring/archive/readings-{full-}{date}.csv.

Five-day flood risk forecast

The flood risk forecast is produced by the Flood Forecasting Centre (FFC) on a daily basis. It is issued more frequently when serious flooding is forecast. It provides the indication of the potential for flooding for five days: the day on which it is issued and the subsequent four days ahead.

The forecast highlights flood risk on a county by county basis and includes a short commentary on the situation. It covers flooding from rivers, the sea, surface water and groundwater for England and Wales.

API

For documentation on the five-day flood forecast API, see https://api.foursources.metoffice.gov.uk/docs/flood-guidance-statement-api-public.

Acknowledgements

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

Data reference