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.

Updates

Version 0.2.0

We have noted some periods of occasional instability due to have query loads. We have addressed this by tightening query rate limits per IP address and improving performance of the problematic queries.

As of this update requests for the latest reading using the ?latest query parameter will now only check a time window of the last 100 days. So measures which have not been updated for longer than that will return an empty result for ?latest. You can override this implicit cutoff by providing an explicit min-date value.

The underlying API infrastructure has been significantly updated but all external behaviour, apart from the above, should be unchanged. Let us know of any issues.

Tracking data

If you wish to maintain a copy of the data then it is more efficient to run daily queries for all readings in the last few days rather than repeatedly query for the latest reading. For example, to track all daily flows in the last 5 days you could use:

Note that all daily flows are updated at most daily so that checking every 15min is not necessary.

API Structure

Each API endpoint provides REST style access to the data via 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.2.0",
    "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,
      ...
    }
    ...
  ]
}

All of the JSON descriptions returned by the API are comprised by metadata and items blocks.

Metadata and Versioning

The metadata description included in JSON and RDF results provides information about the API, such as the publisher and applicable licence. If the resource is also available in other formats, then the hasFormat or dct:hasFormat property will give list of URLs for those alternative formats. See content types for more information about the available 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.2.0",
    "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.

When a list of resources is requested, the metadata description will include any applied limit to the length of the list and offset from the start of the list. They 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 resources in the data. When requesting a description of a single item the items element will still be an array (just with one element). If a list request returns no results then the items array will be empty.

Each item will normally be identified by a URI given in the @id field.

"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 resource references another, the API will typically include key attributes of the referenced resource in-line. Alternatively, you can fetch (i.e. HTTP GET) the URI of the referenced resource to obtain a full description (depending on the URI, the descriptions of related resources may not be served by this API).

Content Types

The descriptions of individual resources can be obtained in multiple formats. When accessing the API through your browser, the format will be HTML, but JSON and RDF formats (RDF/XML and Turtle) are also supported.

Similarly, lists of resources can be obtained in JSON, CSV and HTML and RDF formats. For resources with associated geometries, GeoJSON format is also supported.

To request a specific content type, use standard HTTP content negotiation, for example:

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

You can also request a specific content type by appending a path extension to the URI, or by supplying the extension as the _format query parameter. The supported values 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 results 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.

For example, supply the parameter min-dob=12/03/1993 to query resources with date of birth after 12/03/1993.

You can also specify a filter range using ( and ) for exclusive bounds, and (* and *) for inclusive bounds. The upper and lower boundary values are separated with ... Note that you can use both kinds of boundaries in a single query, eg. friends=(4..17*).

Note When filtering on a range of date-times, to ensure accurate comparison, you should include the timezone on the timestamp that you want to compare values to. For example, to write a timestamp in UTC time, append a Z to the end. See here for more information.

When filtering on resource values, you can reference the resource by its URI or its compact URI, based on the defined namespace prefixes. Note that when URIs are supplied in query parameters, they must be correctly encoded.

type=http%3A%2F%2Fwww.w3.org%2F2004%2F02%2Fskos%2Fcore%23Concept type=skos:Concept

Some endpoints also support referencing resources by just their short names, for example type=Concept.

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.
_count=prop1,prop2... Request an aggregated count query on the given properties. Use @id to denote a count on the total number of results.
_groupBy=prop1,prop2... When requesting an aggregated query using _count, perform a grouping on the given properties.

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

The _projection query parameter lets you specify a set of properties to return for each resource. The properties that are returned by each endpoint by default are defined in "Returned Data" section. You can also specify any of the properties that are documented on the class corresponding to the endpoint result. See the model documentation for full details of the classes in the data model.

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

You can also supply the _withView query parameter (no value is required) to include the properties on selected view in addition to your projection. The view can be selected with the _view query parameter, otherwise the API will use the default view.

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, but they are not intended for presentation to consumers. All URIs are relative to the service base URI of http://environment.data.gov.uk/hydrology.

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|groundwaterLevel} _view={default} search={x} lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d}

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.wiskiID={id} station.stationReference={id} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel|groundwaterLevel} _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|groundwaterLevel} _view={default}

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|groundwaterLevel} period={number} _view={default|flow|full|min}

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|groundwaterLevel} _view={default} search={x} lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d}

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.wiskiID={id} station.stationReference={id} observationType={Qualified|Measured} observedProperty={waterFlow|waterLevel|rainfall|timeLevel|groundwaterLevel} _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|groundwaterLevel} _view={default}

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
/hydrology/id/stations/{station}/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|groundwaterLevel} 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 2020

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

All readings available available from Trews Weir since the start of 2020, 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

Namespace Prefixes

Listed below are supported namespace prefixes. You can use them to specify the URI values of query parameters in short form. For example, ?type=type=http%3A%2F%2Fwww.w3.org%2F2004%2F02%2Fskos%2Fcore%23Concept is equivalent to the prefixed short form, ?type=skos:Concept.

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
datum (rt:datum)
The datum level for the measurement point on OS 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?).
description (dct:description)
A textual description of the item
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.
nrfaStationID (rt:nrfaStationID)
ID of corresponding station in NRFA
nrfaStationURL (rt:nrfaStationURL)
URL for corresponding station in NRFA
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