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

Environment Agency Real Time flood-monitoring API

Survey

Help us to improve this website and API. Complete our short survey.

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:

http://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:

  • http://environment.data.gov.uk/flood-monitoring/id/floods
  • http://environment.data.gov.uk/flood-monitoring/id/floods?min-severity={x}
  • http://environment.data.gov.uk/flood-monitoring/id/3dayforecast
  • http://environment.data.gov.uk/flood-monitoring/id/3dayforecast/image/{day}
  • http://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 http://environment.data.gov.uk/flood-monitoring.

Flood warnings

WhatAPIParameters
All flood warnings and alerts: {root}/id/floods min-severity, county, lat=y&long=x&dist=r

Real time measurements

WhatAPIFilters
All measurement stations: {root}/id/stations parameter=p, parameterName=pn, qualifier=q, town=t, catchmentName=c, riverName=r, RLOIid=r, lat=y&long=x&dist=r, search=x (text in label), status=s, type=t
All measures available from a particular station {root}/id/stations/{id}/measures
All measures from across all the stations: {root}/id/measures parameter=p, parameterName=pn, qualifier=q, stationReference=id, station=uri
All readings for all measures from across all the stations: {root}/data/readings latest, today, date=d, startdate=d1&enddate=d2, parameter=p, parameterName=pn, 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/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):

http://environment.data.gov.uk/flood-monitoring/id/floods/91436

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" http://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:

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 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:

QueryMeaning
?search=xReturn only those items whose label contains x
?lat=y&long=x&dist=dreturn those items whose location falls within d km of the given latitude/longitude (in WGS84 coordinates), this may be approximated by a bounding box.

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 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:

LevelNameMeaning
1Severe Flood WarningSevere Flooding, Danger to Life.
2Flood WarningFlooding is Expected, Immediate Action Required.
3Flood AlertFlooding is Possible, Be Prepared.
4Warning no Longer in ForceThe warning is no longer in force

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:

QueryMeaning
?min-severity=xReturn only warnings which at least as severe as level x
?county=xReturn only warnings applying to flood areas whose county name contains the string x. x can be a list of county names separated by "," in which case alerts which mention any of the named counties will be returned.
?lat=y&long=x&dist=rReturn only warnings applying to flood areas which are within rkm of the given latitude/longitude (in WGS84 coordinates), this may be approximated by a bounding box.

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:

http://environment.data.gov.uk/flood-monitoring/id/floods/{id}

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

FieldMeaningTypeOccurs
descriptionDescriptive name for the flood area affectedxsd:string
eaAreaNameName of the relevant Environment Agency Areaxsd:string
eaRegionNameNo longer usedxsd:string
floodAreaURI for the flood alert or flood warning area affected
floodAreaIDInternal identifier for the flood alert or flood warning area affectedxsd:string
isTidalTrue if the flood is tidal, false if not (fluvial or Groundwater)xsd:boolean
messageThe current situation message, also known as the real time commentaryxsd:stringoptional
severityThe severity of the warning as a text label: 'Flood Alert', 'Flood Warning', 'Severe Flood Warning' or 'Warning no Longer in Force'xsd:string
severityLevelSeverity level code: 1 = 'Severe Flood Warning', 2 = 'Flood Warning', 3 = 'Flood Alert', 4 = 'Warning no Longer in Force'xsd:int
timeMessageChangedThe date and time when the message was last changedxsd:dateTime
timeRaisedThe date and time the warning was last reviewed. Usually (but not always) this leads to a change in the message or severityxsd:dateTime
timeSeverityChangedThe date and time when the severity level was last changedxsd:dateTime

Structure of nested field floodArea:

FieldMeaningTypeOccurs
countyThe name of the county intersecting the flood area, as entered by the Flood Incident Management Teamxsd:string
notationUnique identifier code for the flood area affectedxsd:string
polygonThe boundary of the area encoded as a geoJSON polygonxsd:anyURI
riverOrSeaName of the river or sea area linked to the flood areaxsd:stringoptional

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:

QueryMeaning
?lat=y&long=x&dist=dreturn those areas whose location falls within d km of the given latitude/longitude (in WGS84 coordinates), this may be approximated by a bounding box.

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

FieldMeaningTypeOccurs
countyThe name of the county intersecting the flood area, as entered by the Flood Incident Management Team
descriptionA textual description of the itemxsd:string
eaAreaNameName of the relevant Environment Agency Areaxsd:string
eaRegionNameName of the relevant Environment Agency regionxsd:string
floodWatchAreaThe Flood Watch Area corresponding ot a warningoptional
fwdCodeIdentifying code for the corresponding Target Area in Flood Warnings directxsd:string
labelA name for the itemxsd:string
latlatitude of the centroid of the area, in WGS84 coordinate refxsd:decimal
longlongitude of the centroid of the area, in WGS84 coordinate refxsd:decimal
notationA string or other literal which uniquely identifies the item.xsd:string
polygonThe boundary of the area encoded as a geoJSON polygonxsd:anyURI
quickDialNumberThe QuickDial number of flood line for an English language recordingxsd:stringoptional
riverOrSeaName of the river or sea area linked to the flood areaxsd:stringoptional

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:

QueryMeaning
?parameterName=xReturn only those stations which measure parameters with the given name x, for example Water Level or Flow.
?parameter=xReturn only those stations which measure parameters with the given short form name x, for example level or flow.
?qualifier=xReturn only those stations which measure parameters with qualifier x. Useful qualifiers are Stage and Downstream Stage (for stations such as weirs which measure levels at two locations), Groundwater for groundwater levels as opposed to river levels and Tidal Level for tidal levels.
?label=xReturn only those stations whose label is exactly x.
?town=xReturn only those stations whose town is x. Not all stations have an associated town.
?catchmentName=xReturn only those stations whose catchment name is exactly x. Not all stations have an associated catchment area.
?riverName=xReturn only those stations whose river name is exactly x. Not all stations have an associated river name.
?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.
?type=xReturn only those stations of the given type, where x can be one of SingleLevel, MultiTraceLevel, Coastal, Groundwater or Meteorological
?status=xReturn only those stations with the given status, where x can be one of Active, Closed or Suspended

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

FieldMeaningTypeOccurs
RLOIidIdentifier for the station, as used by River Levels On the Internet.xsd:stringoptional
catchmentNameThe name of the river catchment which this site is related to, if anystringoptional
dateOpenedThe date on which the station openedxsd:dateoptional
datumOffsetOffset between the reference point for how the data is originally recorded and how it is normally displayed. Normally this is the difference between Ordnance datum and the stage datumxsd:decimaloptional
downstageScaleScale limits and historic range for the downstream stage water level measureoptional
labelA name for the itemstring
measuresThe set of measurement types available from the stationrt:Measuremulti-valued
notationA string or other literal which uniquely identifies the item.xsd:string
riverNameName of river associated with this monitoring station (when available)xsd:stringoptional
stageScaleScale limits and historic range for the main stage water level measureoptional
stationReferenceIdentifier for the telemetry feed used by the Environment Agency's National Flood Forecasting Systemstring
townName of the nearest town (or named place) to the stationstringoptional
wiskiIDIdentifier for the station in the WISKI hydrology datasetxsd:stringoptional
lat Latitude of the station, in WGS84 coordinate ref xsd:decimaloptional
long Longitude of the station, in WGS84 coordinate ref xsd:decimaloptional
easting Easting of the station on British National Grid xsd:integeroptional
northing Northing of the station on British National Grid xsd:integeroptional
status The status of the station, one of rt:statusActive, rt:statusClosed or rt:statusSuspended skos:Conceptoptional
statusReason Provides some explanation of the status or change in status of the station xsd:stringoptional
statusDate The date/time of the last update to the status of this station xsd:dateTimeoptional
type A list of types for the station, will be rt:Station plus one of rt:SingleLevel, rt:MultiTraceLevel, rt:Coastal, rt:Groundwater or rt:Meteorological. owl:Class

Structure of nested field measures:

FieldMeaningTypeOccurs
parameterShort, canonical, 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:decimal
qualifierA qualifier 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
unitNameA 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

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.

FieldMeaningTypeOccurs
stageScaleScale information for the main stage water level measurement.rt:Scale
downstageScaleScale information for the downstream water level measurement, if available.rt:Scale

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

FieldMeaningTypeOccurs
highestRecentThe highest reading for this measurement in recent times (typically the last 5 years)rt:Reading
maxOnRecordThe highest reading for this measurement on recordrt:Reading
minOnRecordThe lowest reading for this measurement on recordrt:Reading
scaleMaxThe maximum of the scale suitable for displaying this measurement.xsd:decimal
typicalRangeHighThe top of the typical range band - the measurement exceeded this for 5% of the relevant data on recordxsd:decimal
typicalRangeLowThe bottom of the typical range band - the measurement exceeded this for 95% of the relevant data on recordxsd:decimal

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 Flow.
?parameter=xReturn only measures for parameters with the given short form name x, for example level or flow.
?qualifier=xReturn only those measures with qualifier x. Useful qualifiers are Stage and Downstream Stage (for stations such as weirs which measure levels at two locations), Groundwater for groundwater levels as opposed to river levels and Tidal Level for tidal levels.
?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.

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:

parameterName parameter (short name) Comments
Water Level level Water level, see qualifier for whether stage or downstream of the stage, see unitName for whether relative to the stage datum (mASD) or to the ordnance datum.
Flow flow Water flow rate, only available from some stations. The units of measurement vary between stations so check the unitName carefully.
Wind wind Wind direction and speed available from some stations. The qualifier will indicate whether direction (degrees) or speed (knots or m/s).
Temperature temperature Dry bulb air temperature measurement available from some stations.

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 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: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 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:

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 see the following size limits section.

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

QueryMeaning
?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 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:

QueryMeaning
?parameter=xReturn only readings for measures of parameters with the given short form name x, for example level or flow.
?qualifier=xReturn only readings of measures with qualifier x. Useful qualifiers are Stage and Downstream Stage (for stations such as weirs which measure levels at two locations), Groundwater for groundwater levels as opposed to river levels and Tidal Level for tidal levels.
?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 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.

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

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

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

AffectedRegion (rt:AffectedRegion)
Details of the region affected by the forecast
Coastal (rt:Coastal)
A monitoring station reporting water levels that are either coastal or substantially influenced by tides. Historical high/max/min levels are not relevant and not offered.
DatumType (rt:DatumType)
Class of datum types
DayForecast (rt:DayForecast)
Areas affected for a specific day in the forecast
FloodAlertArea (rt:FloodAlertArea)
A geographic region for which a flood alert may be issued
FloodAlertOrWarning (rt:FloodAlertOrWarning)
An individual flood alert or warning which applies to some FloodArea. The severity level of the alert may be modified over time
FloodArea (rt:FloodArea)
A geographic region for which a flood alert or warning may be issued
FloodWarningArea (rt:FloodWarningArea)
A geographic region for which a flood warning may be issued
Flow (rt:Flow)
Class of measures which return information on Flow
ForecastRisk (rt:ForecastRisk)
Component of a forecast which describes the risks at a specific risk level
GatePosition (rt:GatePosition)
Class of measures which return information on Gate Position
Groundwater (rt:Groundwater)
A monitoring station for groundwater levels (a borehole).
Measure (rt:Measure)
A specific measurement type available from an individual monitoring station
Meteorological (rt:Meteorological)
A monitoring station providing some Meteorological measurements such as wind or air temperature.
MultiTraceLevel (rt:MultiTraceLevel)
A class of monitoring station that reports a pair of water level values - 'stage' and 'downstage'.
RLOIid (rt:RLOIid)
Identifier for the station, as used by River Levels On the Internet.
Rainfall (rt:Rainfall)
Class of measures which return information on Rainfall
Reading (rt:Reading)
An individual measure value taken at some point in time
SingleLevel (rt:SingleLevel)
A class of monitoring station that reports a single water level value
Station (rt:Station)
A environmental monitoring station such as a river level gauge
Temperature (rt:Temperature)
Class of measures which return information on Temperature
ThreeDayForecast (rt:ThreeDayForecast)
Represents a three-day flood forecast with associated regions affected
ValueType (rt:ValueType)
Class of markers for different measurement types
WaterLevel (rt:WaterLevel)
Class of measures which return information on Water Level
Wind (rt:Wind)
Class of measures which return information on Wind
advice (rt:advice)
Statement of advice for risks at this level
affectedRegion (rt:affectedRegion)
A region affected by the forecast risk
catchmentName (rt:catchmentName)
The name of the river catchment which this site is related to, if any
comment (rdfs:comment)
An explanatory comment or description of the term
county (rt:county)
The name of the county intersecting the flood area, as entered by the Flood Incident Management Team
currentWarning (rt:currentWarning)
The current warning for this area, if any
date (rt:date)
The date at which the reading occurred
dateOpened (rt:dateOpened)
The date on which the station opened
dateTime (rt:dateTime)
The date time at which the reading occurred
datum (rt:datum)
The datum level for the measurement point on OS datum
datumAOD (rt:datumAOD)
The level data corresponds to height above the Ordnance Dataum (Newlyn)
datumASD (rt:datumASD)
The level data corresponds to height above the stage datum
datumBDAT (rt:datumBDAT)
The level data corresponds to height below the ?? datum level.
datumOffset (rt:datumOffset)
Offset between the reference point for how the data is originally recorded and how it is normally displayed. Normally this is the difference between Ordnance datum and the stage datum
datumType (rt: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?).
day1image (rt:day1image)
A base64 encoded png image show regions affected on day 1 of the forecast
day2image (rt:day2image)
A base64 encoded png image show regions affected on day 2 of the forecast
day3image (rt:day3image)
A base64 encoded png image show regions affected on day 3 of the forecast
dayForecast (rt:dayForecast)
The details for one day of this forecast
description (dct:description)
A textual description of the item
downstageScale (rt:downstageScale)
Scale limits and historic range for the downstream stage water level measure
eaArea (rt:eaArea)
Identifier for the relevant Environment Agency Area
eaAreaName (rt:eaAreaName)
Name of the relevant Environment Agency Area
eaRegionName (rt:eaRegionName)
Name of the relevant Environment Agency region
floodArea (rt:floodArea)
URI for the flood alert or flood warning area affected
floodAreaID (rt:floodAreaID)
Internal identifier for the flood alert or flood warning area affected
floodWatchArea (rt:floodWatchArea)
The Flood Watch Area corresponding ot a warning
forecastRisk (rt:forecastRisk)
A description of the forecasts risks at some risk level
forecastSummary (rt:forecastSummary)
Textual summary of the forecast
fwdCode (rt:fwdCode)
Identifying code for the corresponding Target Area in Flood Warnings direct
gridReference (rt:gridReference)
The UK grid reference in which the station is located.
highestRecent (rt:highestRecent)
The highest reading for this measurement in recent times (typically the last 5 years)
impact (rt:impact)
Statement of impact of risks at this level
instantaneous (rt:instantaneous)
Measurements which just represent the value at the instance they are taken.
isTidal (rt:isTidal)
True if the flood is tidal, false if not (fluvial)
issueDatetime (rt:issueDatetime)
The date/time at which the forecast was issue
label (rdfs:label)
A name for the item
latestReading (rt:latestReading)
links from a measure the latest available reading
maxOnRecord (rt:maxOnRecord)
The highest reading for this measurement on record
maximum (rt:maximum)
Measurements which represent the maximum over the measurement period.
mean (rt:mean)
Measurements which represent the mean value over the measurement period.
measure (rt:measure)
The URI of the measure being recorded in this reading, this define the location (station), the parameter being measured and other qualifying information.
measures (rt:measures)
The set of measurement types available from the station
message (rt:message)
The current situation message, also known as the real time commentary
minOnRecord (rt:minOnRecord)
The lowest reading for this measurement on record
minimum (rt:minimum)
Measurements which represent the minimum over the measurement period.
notation (skos:notation)
A string or other literal which uniquely identifies the item.
parameter (rt:parameter)
Short, cannonical, name of the quantity being measured e.g. "level", "flow" or "temperature".
parameterName (rt:parameterName)
The name of the quantity being measured e.g. "Water Level", "Flow", "Temperature"
period (rt:period)
The period between successive readings, in seconds.
polygon (rt:polygon)
The boundary of the area encoded as a geoJSON polygon
qualifier (rt: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".
riskLevel (rt:riskLevel)
The risk level for the forecast - High down to Very Low
riverName (rt:riverName)
Name of river associated with this monitoring station (when available)
riverOrSea (rt:riverOrSea)
Name of the river or sea area linked to the flood area
scaleMax (rt:scaleMax)
The maximum of the scale suitable for displaying this measurement.
severity (rt:severity)
The severity of the warning as a text label: 'Flood Alert', 'Flood Warning', 'Severe Flood Warning' or 'Warning no Longer in Force'
severityLevel (rt:severityLevel)
Severity level code: 1 = 'Severe Flood Warning', 2 = 'Flood Warning', 3 = 'Flood Alert', 4 = 'Warning no Longer in Force'
stageScale (rt:stageScale)
Scale limits and historic range for the main stage water level measure
station (rt:station)
The URI of the monitoring station supplying the measure
stationReference (rt:stationReference)
Identifier for the telemetry feed used by the Environment Agency's National Flood Forecasting System
timeMessageChanged (rt:timeMessageChanged)
The date and time when the message was last changed
timeRaised (rt:timeRaised)
The date and time the warning was first raised
timeSeverityChanged (rt:timeSeverityChanged)
The date and time when the severity level was last changed
total (rt:total)
Measurements which represent an accumulated total over the measurement period.
town (rt:town)
Name of the nearest town (or named place) to the station
type (rdf:type)
The class, or classes, of this item
typicalRangeHigh (rt:typicalRangeHigh)
The top of the typical range band - the measurement exceeded this for 5% of the relevant data on record
typicalRangeLow (rt:typicalRangeLow)
The bottom of the typical range band - the measurement exceeded this for 95% of the relevant data on record
unit (rt:unit)
The units in which this parameter is measured, e.g. qudt:Meter
unitName (rt: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).
value (rt: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.
valueType (rt:valueType)
Indicates whether the measured value is an instantaneous reading or a total, mean or maximum over the period.
wiskiID (rt:wiskiID)
Identifier for the station in the WISKI hydrology dataset