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

Water Quality Archive Documentation

Introduction

The Water Quality Archive provides data on water quality measurements carried out by the Environment Agency. Samples are taken from sampling points round the country and then analysed by laboratories to measure aspects of the water quality or the environment at the sampling point. The archive provides data on these measurements and samples dating from 2000 to present day. It contains 58 million measurements on nearly 4 million samples from 58 thousand sampling points.

The archive provides an API to allow selective access to the data, together with the ability to download the data split into either pre-defined or customizable subsets. The data is made available in CSV, JSON and RDF formats.

Licence

This archive is 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:

uses Environment Agency water quality data from the Water Quality Archive (Beta)

API Summary

This is a brief summary of the APIs available, see below for details. In the links in the tables {base} corresponds to http://environment.data.gov.uk/water-quality.

Sampling points

What API Parameters
List sampling points {base}/id/sampling-point
example
search lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d} area={id} subArea={id} samplingPointType={id} samplingPointStatus={open/closed}
Details of one sampling point {base}/id/sampling-point/{id}
example
Samples taken from a sampling point {base}/id/sampling-point/{id}/samples
example
startDate={d} & endDate={d} year={y} purpose={id} isComplianceSample={true/false}
Measurements on samples from a sampling point {base}/id/sampling-point/{id}/measurements
example
startDate={d} & endDate={d} year={y} purpose={id} isComplianceSample={true/false} determinand={id} determinandGroup={id} _sorted
Determinands measured on samples from a sampling point {base}/id/sampling-point/{id}/determinands
example
Count samples by year {base}/id/sampling-point/{id}/countSamples
example

Samples

What API Parameters
List samples {base}/data/sample
example
lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d} area={id} subArea={id} startDate={d} & endDate={d} year={y} purpose={id} isComplianceSample={true/false} samplingPoint={id} samplingPointType={id} sampledMaterialType={id}
Measurements from a particular sample {base}/data/sample/{id}/measurements
example
determinand={id} determinandGroup={id}

Measurements

What API Parameters
List measurements {base}/data/measurement
example
lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d} area={id} subArea={id} startDate={d} & endDate={d} year={y} purpose={id} isComplianceSample={true/false} samplingPoint={id} samplingPointType={id} sampledMaterialType={id} determinand={id} determinandGroup={id} _sorted
Request batch download of measurements {base}/batch/measurement
example
lat={x}&long={y}&dist={d} easting={x}&northing={y}&dist={d} area={id} subArea={id} startDate={d} & endDate={d} year={y} purpose={id} isComplianceSample={true/false} samplingPoint={id} determinand={id} determinandGroup={id} _sorted

Reference data

What API Parameters
List determinands {base}/def/determinands
example
search={x} unit={id} unit.label={x}
List units used with determinands {base}/def/units
example
search={x}
List determinand groups {base}/def/determinand-groups
example
search={x}
List purposes for which samples can be taken {base}/def/purposes
example
search={x}
List Environment Agency areas {base}/id/ea-area
example
search={x}
List Environment Agency sub-areas {base}/id/ea-subarea
example
search={x}
List types of material that can be sampled {base}/def/sampled-material-types
example
search={x}
List types of sampling point {base}/def/sampling-point-types
example
search={x}
List groups of types of sampling point {base}/def/sampling-point-type-groups
example
search={x}

Miscellaneous

What API Notes
List dates the data has been updated {base}/data/modified
example
Returns dates in descending order from the last full update, so limiting to one result will find the last date on which the data was updated
List dates the data has been fully rebuilt {base}/data/rebuilt
example
Returns the date on which the data was last fully rebuilt

The query APIs are subject to a timeout limit, currently set to two minutes. When requesting a very large number of measurements, or measurements selected by a complex query, then the alternative batch request mechanism can be used.

Introduction to the data

Sampling points

These are the locations from which samples are taken. Each has a name (a short label and a longer descriptive comment) and a geographic location (available in both British National Grid and lat/long versions) and is associated with some operational area of the Environment Agency. A list of these areas is available as a map or as data. These areas are used to break up the data into manageable downloadable pieces. There are various types of sampling points.

The archive contains data from sampling points which were in use between 2000 and 2015. Some of these sampling points are no longer in use in which case they will have a status of closed.

Samples

Samples are taken from a sampling point at some date/time, for some defined purpose. The rate of sampling varies widely - some points may be sampled very regularly as part of routine monitoring, others may only be sampled as a result of some specific event. There are many purposes for which a sample can be taken but they broadly divide into either checking compliance with some permit or general monitoring. This is indicated in the data with an isComplianceSample flag.

The material sampled is also indicated. There are many sampled material types possible and these are not limited to the water itself but include associated air, soil and biological samples.

Measurements and Determinands

A sample is analysed to determine one or more properties of the sample or of the associated environment. The properties measured are formally called determinands. In fact the determinand defines not just what has been measured (e.g. dissolved oxygen) but the units the result is expressed in and, implicitly, how the measurement was carried out.

There are a very large number of determinands used in the data (over 7000). To simplify working with these we have created some groupings of useful determinands. It is also possible to query to find out what determinands have ever been measured on samples from a particular sampling point.

The result of a measurement is normally a number, expressed in the units of the determinand. For example, measurement AN-1770585-0237 gives a value of 7.62 mg/l of Magnesium in a surface water sample from Marley Gap in 2014.

However, sometimes a measurement is only an upper or lower bound. For example, the laboratory test may not be able to detect the substance if it is below some concentration. In such cases the measurement will have an associated qualifier. For example, AN-1805502-0119 represents a measurement of less than 0.00059 mg/l of Ammonia (un-ionised as N) on a sample in 2015.

For some determinands the resulting measurement is not a number but a coded value. For example, measurement: MD-1502966-1181 indicates that the weather was Hot (level 5 on a 6 point scale of qualitative weather temperature from Very cold to Very hot) at the time the sample was taken. The example also illustrates that measurements may apply to the environment of the sampling point at the time of the sample, and are not restricted to properties of the sample itself.

API Structure

The APIs provide a REST style access to the data via simple HTTP GET requests which return data in JSON, CSV or RDF formats.

Simple requests

For example fetching data from: http://environment.data.gov.uk/water-quality/id/sampling-point will return a JSON data packet contain a list of some Sampling points:

{
    "@context": "http://environment.data.gov.uk/water-quality/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/water-quality/view/doc/reference",
        "version": "0.1",
        "comment": "WARNING: Pre-alpha test service",
        "hasFormat": [
            "http://environment.data.gov.uk/water-quality/id/sampling-point.csv",
            "http://environment.data.gov.uk/water-quality/id/sampling-point.rdf",
            "http://environment.data.gov.uk/water-quality/id/sampling-point.ttl",
            "http://environment.data.gov.uk/water-quality/id/sampling-point.html" ],
        "limit": 50
    },
    "items": [
        {
            "@id": "http://environment.data.gov.uk/water-quality/id/sampling-point/AN-WOODTON",
            "area": {
                "@id": "http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/1-2",
                "label": "Essex Norfolk and Suffolk"
            },
            "comment": "WOODTON STW FINAL EFFLUENT",
            "easting": 630030,
            "label": "WOODTON STW F/E",
            "lat": 52.492125,
            "long": 1.387003,
            "northing": 293640,
            "samplingPointStatus": {
                "@id": "http://environment.data.gov.uk/water-quality/def/sampling-point-status/open",
                "label": "open"
            },
            "samplingPointType": {
                "@id": "http://environment.data.gov.uk/registry/def/water-quality/sampling_point_types/SA",
                "label": "SEWAGE DISCHARGES - FINAL/TREATED EFFLUENT - WATER COMPANY"
            },
            "subArea": {
                "@id": "http://environment.data.gov.uk/water-quality/id/ea-subarea/1-2-H",
                "label": "NORFOLK TEAM SUB AREA"
            }
        } , ...
    ]
}

The returned JSON data from all API endpoints follows the same structure of three elements: context, metadata and item(s).

The @context reference is placeholder that will, in due course, 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/water-quality/view/doc/reference",
    "version": "0.1",
    "comment": "WARNING: Pre-alpha test service",
    "hasFormat": [
        "http://environment.data.gov.uk/water-quality/id/sampling-point.csv",
        "http://environment.data.gov.uk/water-quality/id/sampling-point.rdf",
        "http://environment.data.gov.uk/water-quality/id/sampling-point.ttl",
        "http://environment.data.gov.uk/water-quality/id/sampling-point.html" ]
    "limit" : 50
}

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

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.

Items and identifiers

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 sampling points) 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 sampling point) 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. So in the earlier example:

{
    "@id": "http://environment.data.gov.uk/water-quality/id/sampling-point/AN-WOODTON",
    "area": {
        "@id": "http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/1-2",
        "label": "Essex Norfolk and Suffolk"
    },
    "comment": "WOODTON STW FINAL EFFLUENT",
    "samplingPointStatus": {
        "@id": "http://environment.data.gov.uk/water-quality/def/sampling-point-status/open",
        "label": "open"
    },
    ...
}

we saw that the first sampling point has a URI identifier of:

http://environment.data.gov.uk/water-quality/id/sampling-point/AN-WOODTON

The items that the sampling point links to, such as the Environment Agency area are also given URIs. In that case the URI is defined in the Environment registry and the same identifier is used in other places, not just the Water Quality Archive:

http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/1-2

Similarly codes from code lists to indicate things like status, purpose, materials, determinands and so on are all given URIs along with descriptive labels.

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, in a variety of formats.

The URIs follow a standard pattern where real identifiable objects or places in the world, such as sampling points, start with id, abstract definitions, such as codes, start with def and real data such as records of samples and measurements start with data.

The API also follows common conventions where a URI of an item in a collection is an extension of the URI for a collection. So that the URI for the collection of all sampling points is:

http://environment.data.gov.uk/water-quality/id/sampling-point

and the URI for a particular sampling point is:

http://environment.data.gov.uk/water-quality/id/sampling-point/{id}

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 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 available in CSV and RDF formats (RDF/XML and Turtle)

To select the desired format use standard HTTP content negation. E.g.:

curl -i -H "Accept: text/csv" http://environment.data.go.uk/water-quality/id/sampling-point?search=clifton

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:

Suffix Type Comment
.json application/json Default
.csv text/csv Only available for list endpoints
.html text/html Special case handling, see below
.ttl text/turtle
.rdf application/rdf+xml

The media type text/html is handled in a special way. HTML is only returned if that is the only media type acceptable (through use of the .html suffix or because that's the only option given in content negotiation accept header). This means that by default you see machine readable data (JSON) even in a web browser (which normally prioritizes HTML over anything else). While this handling is non-standard, feedback (on similar APIs) suggested this is a pragmatically convenient behaviour.

Lists: filtering, paging, sorting, views

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:

This returns all measurements from the sampling point AN-26M19 filtered to only include those from the year 2014 and to only include measurements from the pharmaceuticals group of determinands.

The specific filters available depend on the endpoint and are documented below. Though many endpoints will support a generic text search option search=x which will filter the list for only those whose label or comment fields contain a matching word. Multiple words can be used. For example, the following searches the list of determinands for ones that mention both temperature and water:

The search keywords will be filtered to remove punctuation characters meaningful to the underlying search engine, so only plain alpha-numberic keywords can be reliably used as search terms.

In cases where the value you want to filter on is a URI then there is a shortcut available. Consider the case of searching the list of determinands for those that are measured in a particular unit. The unit given below represents mg/l:

 {
     "@id" : "http://environment.data.gov.uk/water-quality/def/units/0205" ,
     "code" : "0205" ,
     "comment" : "MILLIGRAM PER LITRE" ,
     "inScheme" : {
         "@id" : "http://environment.data.gov.uk/water-quality/def/units/scheme"
      } ,
      "label" : "mg/l" ,
      "prefLabel" : "mg/l" ,
      "type" : [
          { "@id" : "http://qudt.org/schema/qudt#Unit" },
          { "@id" : "http://www.w3.org/2004/02/skos/core#Concept" }
      ]
  }

So the full identifier for the unit is the URI http://environment.data.gov.uk/water-quality/def/units/0205 which can be used to filter the determinand list for those measured in mg/l.

However, the API will also accept a short cut of just the last segment of the URI, 0205 in this case. So that the shorter query is:

It is also possible to achieve the same effect by filtering on the label of the unit, though normally the URI (full or truncated) is the better option:

When filtering on simple literal values such as numbers, strings or true/false then just use those values in the filter. For the case of dates then the date format must follow ISO format, for example 2015-03-01.

In most cases it is possible to apply multiple filters on the sample parameter. This corresponds to a disjunction, a request for information matching either filter value. For example, the follow request lists samples from two sampling points (for the year 2015):

In addition to filtering then list endpoints support a number of view modifiers to control the number of results returned, or their order. All such parameters which affect the presentation of the data but not which items are returned are given a prefix of "_". The main modifiers are:

Query Meaning
?_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. In particular, sampling points, samples and measurements default to a soft limit of 50 items but that can be overridden.
?_offset=x Return the list of items starting with the xth item, together with _limit this enables paging through a long set of results. Though it often cheaper to simply return all that you want in one go or to use filters to reduce the list to a subset of interest.
?_sort=property Reorder the list of returned results by the value of the named property of the results. Use -property to sort in descending instead of ascending order. Multiple _sort parameters can be given.
?_view=viewname Controls how much information about the items is returned.

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.

The _sort is carried out on the server before any limits/offets are applied. So these modifiers together allow you to obtain the first or last few of a longer list. However, the sort options are expense and may lead queries to exceed the query time-out limit. For this reason it is often better to simply request the whole slice of data of interest and then reorder locally for presentation or analysis.

The _view modifier controls how much information is return about the items. Most list endpoints support views of compact, full or default, with the default view being used if no view is explicitly specified.

Viewname Description
compact A minimal view that contains the core information on the item but the values of properties are mostly not expanded. So when those properties link to other resources through URIs it may be necessary to fetch those URIs to fully interpret the results.
default Includes additional properties, and properties of linked resources to enable the result to be interpreted standalone.
full Returns all properties of the item and possibly additional properties of resources linked to the item.

Sampling points

These are the locations from which samples are taken. Each has a name (a short label and a longer descriptive comment) and a geographic location (available in both British National Grid and lat/long versions) and is associated with some operational area of the Environment Agency.

The API for listing sampling points is:

Each sampling point has its own URI from which you can retrieve more information:

The sampling point list can be filtered by:

Query Meaning
search={x} Return sampling points containing {x} in their name (sort label or longer description). If {x} contains multiple words (separated by + in the URL to represent a space) then this will return points with both words in the name.
lat={x}&long={y}&dist={d} Return sampling points within approximately {d}km of the point given by the supplied latitude/longitude (in WGS84 coordinate system). May return those within a square of the given size, rather than a true circle.
easting={x}&northing={y}&dist={d} Returns sampling points within approximately {d}km of the point given by the supplied British National Grid easting/northing. May return those within a square of the given size, rather than a true circle.
area={x} Return sampling points associated with the Environment Agency operational area denoted by {x}, which can be given as a full URI a short-form such as 1-2. A list of areas with their codes can be found using /water-quality/id/ea-area or as a map.
subArea={x} Return sampling points associated with the Environment Agency operational sub-area denoted by {x}, which can given as a full URI a short-form such as 1-2-H. The sub-areas of an area are shown in the list of areas /water-quality/id/ea-area,or you can list all subareas /water-quality/id/ea-subarea.
samplingPointType={id} Return sampling points of the given type, a list of types is available from /water-quality/def/sampling-point-types.
samplingPointType.group={id} Return sampling points whose type is a member of the designated group. Sample point types are grouped into related clusters. For example the FRESHWATER group (notation "F") groups together 19 different individual types of sampling points related to freshwater (such as FRESHWATER - LAKES/PONDS/RESERVOIRS, notation "FA"). A list of groups is available from /water-quality/def/sampling-point-type-groups.
samplingPointStatus={open|closed} Some sampling points are marked as closed and no longer in use. This filter allows you to find only those that are closed or those that are still open.

Results returned

FieldMeaningTypeOccursViews
areaThe area associated with the sampling pointdef-eaorg:Areadefault, full, compact
area.labelA name for the area.rdf:langStringdefault, full
commentAn explanatory comment or description of the sampling point.xsd:stringdefault, full, compact
eastingThe easting of the point on the British National Gridxsd:integerdefault, full, compact
labelA name for the sampling point.rdf:langStringdefault, full, compact
latThe latitude of the point in WGS84 coordinatesxsd:decimaldefault, full, compact
longThe longitude of the point in WGS84 coordinatesxsd:decimaldefault, full, compact
northingThe easting of the point on the British National Gridxsd:integerdefault, full, compact
samplingPointStatusThe status of the sampling point (e.g. open/closed)def-sp:SamplingPointStatusoptionaldefault, full, compact
samplingPointStatus.labelA name for the samplingPointStatus.rdf:langStringdefault, full
samplingPointTypeThe type of the sampling pointdef-sp:SamplingPointTypedefault, full, compact
samplingPointType.labelA name for the samplingPointType.rdf:langStringdefault, full
subAreaThe sub-area associated with the sampling pointdef-eaorg:SubAreaoptionaldefault, full, compact
subArea.labelA name for the subArea.rdf:langStringdefault, full

Samples

Samples are taken from a sampling point at some date/time, for some defined purpose. The rate of sampling varies widely - some points may be sampled very regularly as part of routine monitoring, others may only be sampled as a result of some specific event. There are many purposes for which a sample can be taken but they broadly divide into either checking compliance with some permit or general monitoring.

The API for listing all samples is:

Or to just list samples from a particular sampling point:

To count the number of samples available per-year from a sampling use:

This call will only return information in JSON format and the return items will be objects with year and count values.

Each sample has its own URI from which you can retrieve more information:

It is also possible to list all the measurements on a particular sample:

The sample list can be filtered by:

Query Meaning
lat={x}&long={y}&dist={d} Return samples from sampling points within approximately {d}km of the point given by the supplied latitude/longitude (in WGS84 coordinate system).
easting={x}&northing={y}&dist={d} Return samples from sampling points within approximately {d}km of the point given by the supplied British National Grid easting/northing.
area={x} Return samples from sampling points associated with the Environment Agency operational area denoted by {x}, which can be given as a full URI a short-form such as 1-2. A list of areas with their codes can be found using /water-quality/id/ea-area or as a map.
subArea={x} Return samples from sampling points associated with the Environment Agency operational sub-area denoted by {x}, which can given as a full URI a short-form such as 1-2-H. The sub-areas of an area are shown in the list of areas /water-quality/id/ea-area,or you can list all subareas /water-quality/id/ea-subarea.
samplingPointType={id} Return samples from sampling points of the given type, a list of types is available from /water-quality/def/sampling-point-types.
sampledMaterialType={id} Return samples for which the sample material type has the given notation or URI, a list of materials is available from /water-quality/def/sampled-material-types.html.
year={x} Return samples taken within the given year (e.g. ?year=2015).
startDate={d} & endDate={d} Return samples taken between the two given dates. The date should be specified in ISO 8601 format, for example ?startDate=2015-01-01&endDate=2015-09-30
isComplianceSample={true/false} Return samples which were taken for the purposes of compliance testing (true) or for general monitoring (false).
purpose={id} Return samples taken for the given specific purpose, which can be specified as a URI or a short form. A list of purposes can be obtained from /water-quality/def/purposes.
samplingPoint={id} Return samples taken from the given sampling point, which can be specified as a URI or a short form.
samplingPointType={id} Return samples from sampling points of the given type, a list of types is available from /water-quality/def/sampling-point-types.

Results returned

FieldMeaningTypeOccursViews
isComplianceSampleAn attribute of a :Sample used to indicate whether the sample has been collected for a compliance purpose. The detailed purpose for which the sample has been collected can be determined by examing its :purpose property.xsd:booleanoptionalfull, default, compact
purposeA property for expressing the purpose of a water quality sample was taken.def-sample:Purposeoptionalfull, default, compact
purpose.labelA name for the purpose.rdf:langStringfull, default
sampleDateTimeA property for expressing the date and time that a sample was collected.xsd:dateTimefull, default, compact
sampledMaterialTypeThe type of material sampleddef-sample:SampledMaterialTypeoptionalfull, default, compact
sampledMaterialType.labelA name for the sampledMaterialType.rdf:langStringfull, default
samplingPointThe sampling point at which the sample was takendef-sp:SamplingPointfull, default, compact
samplingPoint.areaThe area associated with the sampling pointdef-eaorg:Areafull
samplingPoint.area.labelA name for the samplingPoint.area.rdf:langStringfull
samplingPoint.eastingThe easting of the point on the British National Gridxsd:integerfull, default
samplingPoint.labelA name for the samplingPoint.rdf:langStringfull, default
samplingPoint.latThe latitude of the point in WGS84 coordinatesxsd:decimalfull
samplingPoint.longThe longitude of the point in WGS84 coordinatesxsd:decimalfull
samplingPoint.northingThe easting of the point on the British National Gridxsd:integerfull, default
samplingPoint.samplingPointStatusThe status of the sampling point (e.g. open/closed)def-sp:SamplingPointStatusoptionalfull
samplingPoint.samplingPointStatus.labelA name for the samplingPoint.samplingPointStatus.rdf:langStringfull
samplingPoint.samplingPointTypeThe type of the sampling pointdef-sp:SamplingPointTypefull
samplingPoint.samplingPointType.labelA name for the samplingPoint.samplingPointType.rdf:langStringfull
samplingPoint.subAreaThe sub-area associated with the sampling pointdef-eaorg:SubAreaoptionalfull
samplingPoint.subArea.labelA name for the samplingPoint.subArea.rdf:langStringfull

Measurements

The measurements are either the results of analysing a sample to determine one or more properties, or they can be properties of the associated environment (such as temperature at the time the sample was taken). The properties measured are more properly called determinands, A determinand defines not just what has been measured (e.g. dissolved oxygen) but the units the result is expressed in and, implicitly, how the measurement was carried out.

The result of a measurement is normally a number, expressed in the units of the determinand. For example, measurement AN-1770585-0237 gives a value of 7.62 mg/l of Magnesium in a surface water sample from Marley Gap in 2014.

However, sometimes a measurement is only an upper or lower bound. For example, the laboratory test may not be able to detect the substance if it is below some concentration. In such cases the measurement will have an associated qualifier. For example, AN-1805502-0119 represents a measurement of less than 0.00059 mg/l of Ammonia (un-ionised as N) on a sample in 2015.

For some determinands the resulting measurement is not a number but some coded value. For example, measurement: MD-1502966-1181 indicates that the weather was Hot (level 5 on a 6 point scale of qualitative weather temperature from Very cold to Very hot) at the time the sample was taken.

The API for listing all measurements is:

Or to just list measurements from a particular sampling point:

or from a particular sample:

Each measurement has its own URI from which you can retrieve the information:

The measurement list can be filtered by:

Query Meaning
lat={x}&long={y}&dist={d} Return measurements from sampling points within approximately {d}km of the point given by the supplied latitude/longitude (in WGS84 coordinate system).
easting={x}&northing={y}&dist={d} Return measurements from sampling points within approximately {d}km of the point given by the supplied British National Grid easting/northing.
area={x} Return measurements from sampling points associated with the Environment Agency operational area denoted by {x}, which can be given as a full URI a short-form such as 1-2. A list of areas with their codes can be found using /water-quality/id/ea-area or as a map.
subArea={x} Return measurements from sampling points associated with the Environment Agency operational sub-area denoted by {x}, which can given as a full URI a short-form such as 1-2-H. The sub-areas of an area are shown in the list of areas /water-quality/id/ea-area,or you can list all subareas /water-quality/id/ea-subarea.
year={x} Return measurements taken within the given year (e.g. ?year=2015).
startDate={d} & endDate={d} Return measurements taken between the two given dates. The date should be specified in ISO 8601 format, for example ?startDate=2015-01-01&endDate=2015-09-30
isComplianceSample={true/false} Return measurements that were taken for the purposes of compliance testing (true) or for general monitoring (false).
purpose={id} Return measurements taken for the given specific purpose, which can be specified as a URI or a short form. A list of purposes can be obtained from /water-quality/def/purposes.
samplingPoint={id} Return measurements taken from the given sampling point, which can be specified as a URI or a short form.
samplingPointType={id} Return measurements from sampling points of the given type, a list of types is available from /water-quality/def/sampling-point-types.
determinand={id} Return measurements of the given determinand, which can be specified as a URI or a short form.
determinandGroup={id} Return measurements of determinands from the given group, which can be specified as a URI or a short form.
_sorted Return the measurements sorted by sample and by date.

Results returned

FieldMeaningTypeOccursViews
codedResultInterpretationGives the interpetation of a coded result value.def-det:CodedResultInterpretationoptionalfull, default, compact
codedResultInterpretation.interpretationThe interpretation of a coded resultfull, default, compact
determinandThe determinand, i.e. the property that was measured.def-det:Determinandfull, default, compact
determinand.definitionThe definition of the determinand.xsd:stringfull, default
determinand.labelA name for the determinand.rdf:langStringfull, default, compact
determinand.notationA string or other literal which uniquely identifies the determinand.full, default
determinand.unitThe units in which the determinand is measured.full, default, compact
determinand.unit.labelA name for the determinand.unit.rdf:langStringfull, default, compact
resultA property for conveying the numeric value of a measurement. The units of measure for interpreting the measurement result are a property of measurements determinand. Some measurements have a coded result (determinand.unit=def-units:0992) in which case an additional codedResult property is present that which references the interpretation of the coded value.xsd:decimalfull, default, compact
resultQualifierA qualifier for the result, e.g. to indicate that the stated result is a lower or upper bound for the actual valuedef-sample:ResultQualifieroptionalfull, default, compact
resultQualifier.notationA string or other literal which uniquely identifies the resultQualifier.full, default, compact
sampleThe sample to which this measurement appliesdef-sample:Samplefull, default, compact
sample.isComplianceSampleAn attribute of a :Sample used to indicate whether the sample has been collected for a compliance purpose. The detailed purpose for which the sample has been collected can be determined by examing its :purpose property.xsd:booleanoptionalfull, default
sample.purposeA property for expressing the purpose of a water quality sample was taken.def-sample:Purposeoptionalfull, default
sample.purpose.labelA name for the sample.purpose.rdf:langStringfull, default
sample.sampleDateTimeA property for expressing the date and time that a sample was collected.xsd:dateTimefull, default, compact
sample.sampledMaterialTypeThe type of material sampleddef-sample:SampledMaterialTypeoptionalfull, default
sample.sampledMaterialType.labelA name for the sample.sampledMaterialType.rdf:langStringfull, default
sample.samplingPointAn open-domained property for making reference to a sampling point.def-sp:SamplingPointfull, default, compact
sample.samplingPoint.areaAn open-domained property for referencing an Environment Agency areadef-eaorg:Areafull
sample.samplingPoint.eastingThe easting of the point on the British National Gridxsd:integerfull, default
sample.samplingPoint.labelA name for the sample.samplingPoint.rdf:langStringfull, default
sample.samplingPoint.latThe latitude of the point in WGS84 coordinatesxsd:decimalfull
sample.samplingPoint.longThe longitude of the point in WGS84 coordinatesxsd:decimalfull
sample.samplingPoint.northingThe easting of the point on the British National Gridxsd:integerfull, default
sample.samplingPoint.subAreaAn open-domained property for referencing an Environment Agency sub-areadef-eaorg:SubAreaoptionalfull

Batch queries

The query APIs are subject to a time-out limit, currently set to two minutes. The batch API provides an alternative query mechanism for obtaining measurements. The API:

This takes the same filter parameters as the /water-quality/data/measurement API. If that set of measurements has previously been generated then the call will return (a redirection to) a cached copy of the results (currently in CSV format only). If no one has requested that particular set of measurements already then a new batch request will be scheduled on a batch processing queue and the call will return (a redirection to) a status page which shows the status of that request in the queue. The status page is available in JSON and HTML format. Repeated fetches of the status page will show the current progress of the request. The queries in the batch processing queue are not subject to time-out so large queries or query results can be accommodated.

The request status in JSON looks like:

{
    "key" : "CB-2003" ,
    "status" : "InProgress" ,
    "positionInQueue" : 0 ,
    "eta" : 86333 ,
    "started" : "2/6/16 8:36 PM"
}

Where the status can be one of Pending InProgress Completed or Failed. The eta element shows the expected time to completion - this is given in ms though the estimate is very approximate and may be inaccurate by minutes or more.

When the batch processing has completed then the status response will change to show a URL from which the result can be download:

{
    "key": "CB-2003",
    "status": "Completed",
    "url": "https://s3-eu-west-1.amazonaws.com/environment-open-data/wims/cache/CB-2003.csv"
}

In addition, it is also possible to POST a query to the same batch API. The filter settings can still be provided in the query parameters, just as for GET requests, but in addition it is possible to send the filter parameters in the body of the POST request in application/x-www-form-urlencoded format. This allows larger sets of filters values to be sent, for example in order to request information from a large number of specific sampling points.

The result of a successful batch query POST submission will be a 201 (Created) response with a location header giving the URL of the status information on the request, in the same format as the above.

Determinands and units

Determinands identify a property which can be measured on a sample or the sampling environment, together with the units in which the result of that measurement will be expressed. There are over 7000 such determinands within the Water Quality Archive. A number of API calls are provided to assist with finding determinands:

What API Parameters
List determinands {base}/def/determinands
example
search={x} unit={id} unit.label={x}
List units used with determinands {base}/def/units
example
search={x}
List determinand groups {base}/def/determinand-groups
example
search={x}
Determinands measured on samples from a sampling point {base}/id/sampling-point/{id}/determinands
example

Results returned - determinands

FieldMeaningTypeOccursViews
definitionThe definition of the Determinand.rdf:langStringdefault, compact, full
labelA name for the Determinand.rdf:langStringdefault, compact, full
notationA string or other literal which uniquely identifies the Determinand.default, compact, full
unitThe units in which the Determinand is measured.default, compact, full
unit.commentAn explanatory comment or description of the unit.xsd:stringoptionaldefault, compact, full
unit.labelA name for the unit.rdf:langStringdefault, compact, full

Results returned - units

FieldMeaningTypeOccursViews
codeThe UK water quality archive code for a unit.default
commentAn explanatory comment or description of the unit.xsd:stringdefault
labelA name for the unit.rdf:langStringdefault
notationA string or other literal which uniquely identifies the unit.optionaldefault
typeThe class or type of this unit.xsd:stringdefault

Other reference information

A number of other codes or entities are used in the data and the set of legal values for these can be listed using the the follow API calls.

What API
List purposes for which samples can be taken {base}/def/purposes
example
List Environment Agency areas {base}/id/ea-area
example
List Environment Agency sub-areas {base}/id/ea-subarea
example
List types of material that can be sampled {base}/def/sampled-material-types
example
List types of sampling point {base}/def/sampling-point-types
example
List groups of types of sampling point {base}/def/sampling-point-type-groups
example

These all support filtering by text search using the search={x} parameter.

Data reference

Area (def-eaorg:Area)
Area are organisational units of the Environment Agency that are sub-organizations of an Environment Agency region.
CodedResultInterpretation (def-det:CodedResultInterpretation)
CodedResultInterpretation carry a coded result {resultCode) and its narrative interpretation for use in decoding coded result measurements of a determinand.
Determinand (def-det:Determinand)
A subclass of skos:Concept for Environmental Monitoring determinands.
EAOrgUnit (def-eaorg:EAOrgUnit)
Organizational Units of the Environment Agency, including Region, Area and SubArea.
Measurement (def-sample:Measurement)
A class for measurements of some determinand made on a particular sample.
Purpose (def-sample:Purpose)
A distinguished sub-class of skos:Concept for expressing the purpose for which a water quality sample was taken.
PurposeGroup (def-sample:PurposeGroup)
A subclass of skos:Collection use to collect WIMS sampling purposes used for meet some higher level objective, for example Monitoring or Compliance.
Region (def-eaorg:Region)
Regions are the largest organizational sub-unit of the Environment Agency
Sample (def-sample:Sample)
A class for samples taken for water quality monitoring and compliance purposes.
SampledMaterialType (def-sample:SampledMaterialType)
A sub-class of skos:Concept for categories of sampled material, e.g. sea-water-intertidal.
SamplingPoint (def-sp:SamplingPoint)
The class of sampling points monitored by a responsible body.
SubArea (def-eaorg:SubArea)
Sub-area are are organizational units of the Environment Agency that are sub-organisations of an area.
area (def-eaorg:area)
An open-domained property for referencing an Environment Agency area
closed (def-sps:closed)
sampling point status: closed. Sampling points that have not been used for 2 years should be marked closed.
code (def-unit:code)
The UK water quality archive code for a unit.
codedResultInterpretation (def-det:codedResultInterpretation)
An open domained property for referencing a CodedResultInterpretation, typically used with a determinand, a sample or a measurement.
comment (rdfs:comment)
An explanatory comment or description of the {x}.
country (def-sp:country)
An open-domained property for making reference to a country. (TBD find a more widely used term from a common vocab to substitute).
definition (skos:definition)
The definition of the {x}.
description (dct:description)
A textual description of the {x}.
determinand (def-det:determinand)
An open-domained property for referencing a determinand
determinandNotation (def-det:determinandNotation)
A distinguished subproperty of skos:notation used to carry notation values for determinands.
easting (spatialrelations:easting)
The easting of the point on the British National Grid
greaterThan (:greaterThan)
Indicates that the value of the qualified result is greater than the value given and can, but not always, apply where the measurement result is above the permitted value or recommended level.
interpretation (def-det:interpretation)
The interpretation of a coded result
isComplianceSample (def-sample:isComplianceSample)
An attribute of a :Sample used to indicate whether the sample has been collected for a compliance purpose. The detailed purpose for which the sample has been collected can be determined by examing its :purpose property.
label (rdfs:label)
A name for the {x}.
lat (w3cgeo:lat)
The latitude of the point in WGS84 coordinates
lessThan (:lessThan)
Indicates that the qualified result is either below the minimum level of detection or under the minimum reporting value.
long (w3cgeo:long)
The longitude of the point in WGS84 coordinates
measurement (def-sample:measurement)
An open domained property for making general reference to a measurement.
member (skos:member)
A member of the group.
negative (:negative)
Indicates that the qualified result has a negative value.
northing (spatialrelations:northing)
The easting of the point on the British National Grid
notation (skos:notation)
A string or other literal which uniquely identifies the {x}.
open (def-sps:open)
sampling point status: open. Sampling points that have not been used for 2 years should be marked closed.
purpose (def-sample:purpose)
A property for expressing the purpose of a water quality sample was taken.
purposeNotation (def-sample:purposeNotation)
A distinguished subproperty of skos:notation for sampling purposes.
region (def-eaorg:region)
An open-domained property for referencing an Environment Agency region.
result (def-sample:result)
A property for conveying the numeric value of a measurement. The units of measure for interpreting the measurement result are a property of measurements determinand. Some measurements have a coded result (determinand.unit=def-units:0992) in which case an additional codedResult property is present that which references the interpretation of the coded value.
resultCode (def-det:resultCode)
An open domained property that carries a result code.
resultQualifier (def-sample:resultQualifier)
A qualifier for the result, e.g. to indicate that the stated result is a lower or upper bound for the actual value
sameAs (owl:sameAs)
An alternative URI resource equivalent to this {x}.
sample (def-sample:sample)
An open domained property for making general reference to a sample.
sampleDateTime (def-sample:sampleDateTime)
A property for expressing the date and time that a sample was collected.
sampledMaterialType (def-sample:sampledMaterialType)
The type of material sampled
samplingMechanism (def-sample:samplingMechanism)
An open-domained property for referring to a sampling mechanism
samplingPoint (def-sp:samplingPoint)
An open-domained property for making reference to a sampling point.
samplingPointStatus (def-sp:samplingPointStatus)
The status of the sampling point (e.g. open/closed)
samplingPointType (def-sp:samplingPointType)
The type of the sampling point
scheme (:scheme)
A SKOS Concept Scheme for Result Qualifiers.
subArea (def-eaorg:subArea)
An open-domained property for referencing an Environment Agency sub-area
type (rdf:type)
The class or type of this {x}.
unit (qudt:unit)
The units in which the {x} is measured.
unknown (:unknown)
Indicates that the source data contained an unrecognised result qualifier. No measurements should have this value assigned as a result qualifier.
upstreamSamplingPoint (def-sp:upstreamSamplingPoint)
An open-domained property for making reference to an upstream sampling point.
wimsEaAreaCode (def-eaorg:wimsEaAreaCode)
A property of an :Area which carries the coded value used internally withn WIMS to reference EA Areas.