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

Environment Agency Tide Gauge API

Introduction

The UK National Tide Gauge Network is owned and operated by the Environment Agency on behalf of the UK Coastal Flood Forecasting service (a partnership between the Environment Agency, Natural Resources Wales, the Scottish Environment Protection Agency and Northern Ireland Department for Infrastructure – Rivers. It records tidal elevations at 44 locations around the UK coast. Data is made available in near real time with measurements reported every 15 mins. The measurements provide mean sea level within each 15 min window and are reported both relative to local datum (unit m) and relative to the Ordnance Datum at Newlyn (unit mAOD).

The Tide Gauge API provides access to these measurements, and to information on the monitoring stations providing those measurements. It is compatible with (and integrated into) the API for water level/flow and rainfall readings. The API data is normally updated every 15 mins so typically the latest available reading will lag between 15 and 30 mins.

Note that all times given by the API are in GMT (also known as UTC), as indicated by the Z suffix (see XML Schema datatypes).

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 tide gauge 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.

Application

To view the data interactively see the Tide Gauge Readings application.

Note that for convenience the application will display times in local time (i.e. BST during the summer) whereas the underlying data from the API is given in UTC/GMT.

The open source code for this application is available from github.

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 tide gauge measurements

WhatAPIFilters
All tide gauge stations: {root}/id/stations?type=TideGauge unitName=m|mAOD, lat=y&long=x&dist=r, search=x (text in label)
Measure available from a particular station (includes latest reading): {root}/id/stations/{id}/measures
Information on from a particular station: {root}/id/stations/{id}
Find related station providing alternate datum: {root}/id/stations/{id}/linked
All measures from across all the stations (includes latest reading): {root}/id/measures?stationType=TideGauge unitName=m|mAOD, stationReference=id, station=uri, search=x (text in label)
All readings for all measures from across all the stations: {root}/data/readings?stationType=TideGauge latest, today, date=d, startdate=d1&enddate=d2, since=dt, stationReference=id, station=uri, unitName=m|mAOD, _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/stations/E72639

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.9",
    "comment": "Status: Beta service",
    "hasFormat": [
      "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639.rdf",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639.ttl",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639.html"
    ]
  },
   "items": {
    "@id": "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639",
    "RLOIid": "3014",
    "dateOpened": "2012-02-24",
    "eaAreaName": "Anglian - Wessex",
    "eaRegionName": "Anglian",
    "gridReference": "ST 4953 7815",
    "label": "Avonmouth Portbury",
    ...
  }
}

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.9",
    "comment": "Status: Beta service",
    "hasFormat": [
      "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639.rdf",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639.ttl",
      "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639.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.9",
    "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 an exapanded version of the earlier example:

  "items": {
    "@id": "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639",
    "RLOIid": "3014",
    "dateOpened": "2012-02-24",
    "eaAreaName": "Anglian - Wessex",
    "eaRegionName": "Anglian",
    "gridReference": "ST 4953 7815",
    "label": "Avonmouth Portbury",
    "lat": 51.49999,
    "long": -2.728468,
    "measures": {
      "@id": "http://environment.data.gov.uk/flood-monitoring/id/measures/E72639-level-tidal_level-Mean-15_min-mAOD",
      "datumType": "http://environment.data.gov.uk/flood-monitoring/def/core/datumAOD",
      "label": "Avonmouth Portbury - level-tidal_level-Mean-15_min-mAOD",
      "latestReading": {
        "@id": "http://environment.data.gov.uk/flood-monitoring/data/readings/E72639-level-tidal_level-Mean-15_min-mAOD/2017-04-03T10-00-00Z",
        "date": "2017-04-03",
        "dateTime": "2017-04-03T10:00:00Z",
        "measure": "http://environment.data.gov.uk/flood-monitoring/id/measures/E72639-level-tidal_level-Mean-15_min-mAOD",
        "value": 3.506
      },
      ...
  }

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

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 are of type TideGauge.

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 tide level, rainfall, water levels and flows taken at a variety of measurement stations. In general a given station may provide more than one set of measurements, for example, some stations measure both rainfall and air temperature. However, tide gauge stations only provides a single measure - different notional stations are provided at each location for the two datum options (local datum and Ordnance Datum). 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 tide gauge measurement, or some subset thereof:

Supports the following filter parameters:

QueryMeaning
?unitName=xReturn only those stations whose measure provides values in the given units, either m (for metres from local datum) or mAOD (for metres relative to Ordnance Datum at Newlyn).
?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. Only some tide gauge stations have RLOI identifiers..
?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 tide gauge stations returning measurements relative to Ordnance Datum:

List all tide gauge stations in the vicinity of Portishead:

Returned data

FieldMeaningTypeOccurs
labelA name for the itemstring
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
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
type A list of types for the station, will include rt:TideGauge. owl:Classoptional

For those stations that are include in the River Levels On the Internet (RLOI) dataset then additional information is avaiable:

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
riverNameName of river associated with this monitoring station (when available)xsd:stringoptional
stageScaleScale limits and historic range for the main stage water level measureoptional
townName of the nearest town (or named place) to the stationstringoptional
wiskiIDIdentifier for the station in the WISKI hydrology datasetxsd:stringoptional
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

Structure of nested field measures:

FieldMeaningTypeOccurs
parameterShort, canonical, name of the quantity being measured - "level".string
parameterNameThe name of the quantity being measured - "Water Level".string
periodThe period between successive readings, in seconds.xsd:decimal
qualifierA qualifier for the quantity being measured - "Tidal Level".string
unitNameA name for the units for this measurement - "m" or "mAOD".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.

Tide gauge stations are provided in pairs. Each offer 15 minute mean levels at the same location but with different datum - local v.s. national Ordnance Datum at Newlyn. To easily discover the corresponding station use the /linked endpoint. Thus:

Will return:

  items": [ {
    "localDatumStation": "http://environment.data.gov.uk/flood-monitoring/id/stations/E72624"
  } ]

Correspondingly:

Will return

  items": [ {
    "ordnanceDatumStation": "http://environment.data.gov.uk/flood-monitoring/id/stations/E72639"
  } ]

Both provide measurements at Avonmouth Portbury.

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
?unitName=xReturn only measures which return values in the given units, m or mAOD.
?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.
?stationType=xReturn only readings of measures which are available from the station with given type x, e.g. TideGauge.
?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 (in UTC) 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, e.g. Tidal+Level.
?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.
?stationType=xReturn only readings of measures which are available from the station with given type x, e.g. TideGauge.

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 value for all measurements relative to Ordanace Datum in CSV format:

Return all readings for a single tide 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.