Introduction

The Hydrology API provides access to historic water flow information. It complements the near real-time data provided under /flood-monitoring in that it provides access to a long term archive of quality checked and qualified data.

The API and data model for the /hydrology API differs slightly from that under /flood-monitoring due to intrinsic differences (e.g. presence of quality flags on each reading for qualified data), modelling changes (e.g. adding links to SOSA/SSN terms) and technology differences.

In addition Environment Agency are moving to using new identifiers for monitoring stations based on GUIDs and the station URIs provided by this API use these new standards. For convenience, the stations shown here provide annotations showing the old stationReference notations (as well as the River Levels on the Internet and WISKI notations) and provide sameAs links to the equivalent /flood-monitoring stations.

For convenience the corresponding real-time flow data for each station will be made available here, under the same API scheme, in due course.

API Summary

This is a brief summary of the APIs available, see below for details. Note that the HTML views are offered as an aid to debugging and development, they are not intended for presentation to consumers. All URIs are relative to the service base URI of http://environment.data.gov.uk.

Monitoring Stations

Information on monitoring stations at which flows and levels are monitored.

Description API Parameters
Details for a single monitoring station. /hydrology/id/stations/{id}
[json] [html]
id={value} _view={default}
List of all monitoring stations can be filtered by name, location and other parameters. /hydrology/id/stations
[json] [html]
RLOIid={id} wiskiID={id} stationReference={id} sampleOf={waterbody} observedProperty={waterFlow|waterLevel|rainfall|timeLevel} _view={default} lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d} search={x}

Measures

Measurement timeseries available.

Description API Parameters
Description of a single measurement timeseries /hydrology/id/measures/{id}
[json] [html]
id={value} _view={default}
List of all available measurement timeseries in the hydrology dataset. /hydrology/id/measures
[json] [html]
station={guid} station.RLOIid={id} station.wiskiID={id} station.stationReference={id} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel} _view={default}
List the timeseries for a station. /hydrology/id/stations/{station}/measures
[json] [html]
station={value} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel}

Readings

Readings (aka observations or datapoints) within a measurement timeseries

Description API Parameters
Readings for a single measure timeseries. /hydrology/id/measures/{measure}/readings
[json] [html]
measure={value} date={yyyy-mm-dd} min-date={yyyy-mm-dd} mineq-date={yyyy-mm-dd} max-date={yyyy-mm-dd} maxeq-date={yyyy-mm-dd} earliest={} latest={} _view={default|flow|full|min}
Readings for one or more measure time series. /hydrology/data/readings
[json] [html]
measure={id} date={yyyy-mm-dd} min-date={yyyy-mm-dd} mineq-date={yyyy-mm-dd} max-date={yyyy-mm-dd} maxeq-date={yyyy-mm-dd} earliest={} latest={} station={guid} station.RLOIid={id} station.wiskiID={id} station.stationReference={id} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel} period={number} _view={default|flow|full|min}

API Structure

The APIs provide a REST style access to the data via simple HTTP GET requests. Data can be returned in a range of formats including JSON, CSV and web pages.

Simple Requests

For example fetching a list of resources from: /hydrology/id/stations.json?_limit=5

will return a JSON data packet similar to the following:

{
  "meta": {
    "comment": "Test version of hydrology API, alpha",
    "license": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "licenseName": "OGL 3",
    "publisher": "Environment Agency",
    "version": "0.1",
    "limit": 10
  },
  "items": [
    {
      "@id": "http://environment.data.gov.uk/hydrology/id/stations/353a6f59-bc41-5bb8-a00e-82b67897d052",
      "easting": 275112,
      "label": "AUSTINS BRIDGE",
      "lat": 50.479041,
      "long": -3.761515,
      "measures": { ... }
      "northing": 65841,
      ...
    }
    ...
  ]
}

The returned JSON data from all API endpoints follows the same structure of elements: metadata and items.

Metadata and Versioning

The metadata block 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 by a suffix, see content types).

{
  "meta": {
    "comment": "Test version of hydrology API, alpha",
    "license": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "licenseName": "OGL 3",
    "publisher": "Environment Agency",
    "version": "0.1",
    "limit": 10
  },
  ...
}

The metadata block also includes version number information. The intention is that, after initial release, 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 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, as in the example above.

Items

The items element in the JSON response will be an array containing objects describing items in the data. If requesting a description of a single item the items element will still be an array (just with one element). If a list search returns no results then the items array will be empty.

Each item will normally be identified by a URI given in the @id field. It is often possible to just use the last element of the URI When referencing items in API calls.

"items": [
  {
    "@id": "http://environment.data.gov.uk/hydrology/id/stations/353a6f59-bc41-5bb8-a00e-82b67897d052",
    "easting": 275112,
    "label": "AUSTINS BRIDGE",
    "lat": 50.479041,
    "long": -3.761515,
    "measures": { ... }
    "northing": 65841,
    ...
  }
  ...
]

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

Content Types

The descriptions of individual items can be obtained in multiple formats. The default format is HTML, but all item descriptions can also return information in JSON and RDF formats (RDF/XML and Turtle).

Similarly lists of items can be obtained in JSON, CSV and HTML as well as RDF formats. In the case of items with associated geometries, GeoJSON format is also supported.

To select the desired format use standard HTTP content negotiation, for example:

curl -i -H "Accept: text/csv" /hydrology/id/stations.json?_limit=5

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

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

So the earlier example is equivalent to simply fetching the URL:

By default the CSV content returns will use column names matching the property paths in the corresponding JSON format.

Lists: Filtering and Paging

Some endpoints return information describing a single identified item but many return information on a list of items. Such list endpoints support query parameters to filter the list to only include some items. In most cases these filters take the form:

prop1.prop2...propn=value

Here, the props are the short property names that appear in the JSON format and the value is the value that the property is required to have. The value might be a number, a string, a date or a URI. In the case of the URI then you can often use the last segment of the URI on its own. For example, to list just protected areas of type Special Area of Conservation (SAC) use:

If the same filter is used twice with different values then the API will return results for both values (i.e. it acts as a disjunction).

You can apply prefixes to the parameter in order to apply standard filters to your query:

Prefix Meaning
min- Applies a strictly greater than filter.
mineq- Applies a greater than or equal to filter.
max- Applies a strictly less than filter.
maxeq- Applies a less than or equal to filter.

An example would be min-dob=12/03/1993 to query resources with date of birth after 12/03/1993.

You are also allowed to set a range filter using parentheses, i.e. ( and ) for setting an exclusive bound and (* and *) to sent an exclusive bound. Make sure to separate values with .. Be aware that you can also mix and match the boundaries having one inclusive and one exclusive. For example friends=(4..17*)

List endpoints also support view modification parameters. These are distinguished by starting with an underscore character. The commonly supported modifiers are:

Query Meaning
_view=full|.. An alternative view of the items. The default view includes just summary properties. The full view includes everything.
_limit=x Return only x items from the list, some endpoints may impose a default limit and/or a maximum to which the limit can be set.
_offset=x Return the list of items starting with the xth item, together with _limit this enables paging through a long set of results.
_sort=prop.prop... Reorder the list of results in ascending order of the given property (or property chain). To sort in descending order use _sort=-prop. More than one sort can be included in which case they will be applied in order.

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.

Projection

A _projection parameter lets you return a subset of properties that are specified by the endpoint view. All the properties returned by an endpoint are defined in Returned Data section.

  • Use . to specify nested properties: prop1.prop12
  • Use () in case you want to specify multiple child properties: prop1(prop12,prop13).
    This is just a shorthand for prop1.prop12,prop1.prop13
  • Use wildcard * to request all nested properties: prop1(*).
    The wildcard is not recursive and will only include the immediate child properties.

In case there are multiple views defined on the endpoint the projection will apply on the default view unless a _view parameter is specified as well.

Monitoring Stations

Information on monitoring stations at which flows and levels are monitored.

See below for examples of useful filter parameters for each endpoint.

Description API Parameters
Details for a single monitoring station. /hydrology/id/stations/{id}
[json] [html]
id={value} _view={default}
List of all monitoring stations can be filtered by name, location and other parameters. /hydrology/id/stations
[json] [html]
RLOIid={id} wiskiID={id} stationReference={id} sampleOf={waterbody} observedProperty={waterFlow|waterLevel|rainfall|timeLevel} _view={default} lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d} search={x}

Examples

Find the station with WIKSI identifier S11512_FW:

Find the station with old-style telemetry station reference 45121:

All stations on the water body Bolingey Stream which have measurements for water flow:

All stations with 3km of the given coordinates:

Returned data

/hydrology/id/stations/{id}
Show
/hydrology/id/stations
Show

Measures

Measurement timeseries available.

See below for examples of useful filter parameters for each endpoint.

Description API Parameters
Description of a single measurement timeseries /hydrology/id/measures/{id}
[json] [html]
id={value} _view={default}
List of all available measurement timeseries in the hydrology dataset. /hydrology/id/measures
[json] [html]
station={guid} station.RLOIid={id} station.wiskiID={id} station.stationReference={id} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel} _view={default}
List the timeseries for a station. /hydrology/id/stations/{station}/measures
[json] [html]
station={value} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel}

Examples

Timeseries available for station with give GUID identifier:

Timeseries of Qualified data from station idenified by WISKIid:

Returned data

/hydrology/id/measures/{id}
Show
/hydrology/id/measures
Show

Readings

These endpoints return readings (aka observations or datapoints) within a measure timeseries, or set of timeseries.

Each reading has a date-time stamp, a value (usually) and the identifier for the measure (timeseries). For Qualified data there can be up to three quality flags:

Quality flagMeaningValues
quality The quality of this reading Good Estimated Suspect Unchecked Missing
completeness Whether the value is based on complete data or not Complete Incomplete
qflag Other qualifying information. Edited
WithinRating
NoRating
ExtrapolateUpperPart
ExtrapolateLowerPart
BeyondUpperLimit
BeyondLowerLimit
WeirModularHead
WeirNonModularHead
WeirExtremelyNonModularHead
WeirModularTail
WeirNonModularTail
WeirExtremelyNonModularTail
WeirModularCrest
WeirNonModularCrest
WeirExtremelyNonModularCrest
WeirHeadOnly
RasteredTimeStamp
Apportioned
Dry
Snow
Trace

For Qualified data then readings with quality annotation Missing will not include a value at all.

Data is returned in sorted order, earliest to latest.

See below for examples of useful filter parameters for each endpoint.

Description API Parameters
Readings for a single measure timeseries. /hydrology/id/measures/{measure}/readings
[json] [html]
measure={value} date={yyyy-mm-dd} min-date={yyyy-mm-dd} mineq-date={yyyy-mm-dd} max-date={yyyy-mm-dd} maxeq-date={yyyy-mm-dd} earliest={} latest={} _view={default|flow|full|min}
Readings for one or more measure time series. /hydrology/data/readings
[json] [html]
measure={id} date={yyyy-mm-dd} min-date={yyyy-mm-dd} mineq-date={yyyy-mm-dd} max-date={yyyy-mm-dd} maxeq-date={yyyy-mm-dd} earliest={} latest={} station={guid} station.RLOIid={id} station.wiskiID={id} station.stationReference={id} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel} period={number} _view={default|flow|full|min}

Examples

Earliest reading available from Trews Weir

Latest reading available from Trews Weir

All readings available available from Trews Weir since the start of 2018

All readings available available from Trews Weir since the start of 2018, as json

All readings available available from Trews Weir since the start of 2018, as a CSV file

Readings for all timeseries from station with reference 47119 for a particular day

Readings for all timeseries with period one day, for a particular day

Readings for all timeseries with qualified data, for a particular day

Returned data

/hydrology/id/measures/{measure}/readings
Show
/hydrology/data/readings
Show

Data reference

RLOIid (rt:RLOIid)
Identifier for the station, as used by River Levels On the Internet.
Station (rt:Station)
A environmental monitoring station such as a river level gauge
TimeSeries (core:TimeSeries)
A slice of a dataset organized as a time series of observations for a particular sampling point
catchmentName (rt:catchmentName)
The name of the river catchment which this site is related to, if any
dateOpened (rt:dateOpened)
The date on which the station opened
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?).
inManagementUnit (core:inManagementUnit)
Indicates that the feature or region is within or at least managed as part of the management unit
inRegion (core:inRegion)
Indicates a region which a feature or other entity is linked to. Usually means the feature is partly or wholly enclosed in the region but may reflect other relationships
label (rdfs:label)
A name for the item
measurementRange (core:measurementRange)
Indicates the historic and typical range of values for observations in this series
measures (rt:measures)
The set of measurement types available from the station
notation (skos:notation)
A string or other literal which uniquely identifies the item.
observationType (core:observationType)
Indicates the nature of the observations in a dataset, for example raw measured v.s. quality controlled
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.
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".
riverName (rt:riverName)
Name of river associated with this monitoring station (when available)
sampleOf (core:sampleOf)
A larger feature which sampling point measures, samples or represents
sampledBy (core:sampledBy)
A sampling point related to this feature, may be a measurement station or a point at which samples are taken.
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
status (rt:status)
Indicates whether a station is active, suspended or closed
town (rt:town)
Name of the nearest town (or named place) to the station
type (rdf:type)
The class, or classes, of this item
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 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).
valueStatistic (core:valueStatistic)
Indicates whether the values in a time series represent mean, min, max, instananteous or other statistics over the measurement interval.
wiskiID (rt:wiskiID)
Identifier for the station in the WISKI hydrology dataset