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

Catchment Data API Reference Documentation

Introduction

The Catchment Data Explorer (CDE) helps you explore and download information about the water environment. It supports and builds upon the data in the river basin management plans. The Catchment Data API complements this by providing selective programmatic access to the data.

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/catchment-planning. These API links are live examples and will typically return a web page view of the resulting data.

River Basin Districts (RBD)

WhatAPIParameters
List River Basin Districts {root}/so/RiverBasinDistrict search=x _limit=n _view=default|full
A single River Basin District {root}/so/RiverBasinDistrict/{id}
Boundary polygon for a River Basin District (as GeoJSON) {root}/so/RiverBasinDistrict/{id}/polygon
Management catchments in district {root}/so/RiverBasinDistrict/{id}/management-catchments search=x _limit=n _view=default|full
Operational catchments in district {root}/so/RiverBasinDistrict/{id}/operational-catchments search=x _limit=n _view=default|full
Water bodies in district {root}/so/RiverBasinDistrict/{id}/water-bodies search=x _limit=n _view=default|full

Management Catchments

WhatAPIParameters
List Management Catchments {root}/so/ManagementCatchment inRiverBasinDistrict=n search=x _limit=n _view=default|full
A single Management Catchment {root}/so/ManagementCatchment/{id}
Boundary polygon for a Management Catchment (as GeoJSON) {root}/so/ManagementCatchment/{id}/polygon
Operational catchments in Management Catchment {root}/so/ManagementCatchment/{id}/operational-catchments search=x _limit=n _view=default|full
Water bodies in Management Catchment {root}/so/ManagementCatchment/{id}/water-bodies search=x _limit=n _view=default|full

Operational Catchments

WhatAPIParameters
List Management Catchments {root}/so/OperationalCatchment inManagementCatchment=n inRiverBasinDistrict=n search=x _limit=n _view=default|full
A single Operational Catchment {root}/so/OperationalCatchment/{id}
Boundary polygon for a Operational Catchment (as GeoJSON) {root}/so/OperationalCatchment/{id}/polygon
Water bodies in Operational Catchment {root}/so/OperationalCatchment/{id}/water-bodies search=x _limit=n _view=default|full

Water Bodies

WhatAPIParameters
List Water Bodies {root}/so/WaterBody waterBody=notation type=t OperationalCatchment=n inManagementCatchment=n inRiverBasinDistrict=n search=x polygon={geojson}_limit=n _view=default|full|minimal|csv
A single Water Body {root}/so/WaterBody/{id}
A single Water Body, specific version {root}/so/WaterBody/{id}/{version}
Boundary polygon for a Water Body (most recent version, as GeoJSON) {root}/so/WaterBody/{id}/polygon
River Line geometry if the Water Body is a river (most recent version, as GeoJSON) {root}/so/WaterBody/{id}/river-line
Classifications for a Water Body {root}/so/WaterBody/{id}/classifications cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}
Objectives for a Water Body {root}/so/WaterBody/{id}/objective-outcomes cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}
Predicted outcomes for a Water Body {root}/so/WaterBody/{id}/predicted-outcomes cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}
Investigations relating to a Water Body {root}/so/WaterBody/{id}/investigations _limit=n _sort={param}
RNAG (Reasons for not achieving good) relating to a Water Body {root}/so/WaterBody/{id}/reasons-for-failure businessSector=bs pressureTier1=p pressureTier2=p pressureTier3=p swmi=s exists-action=true|false classificationItem={code} _limit=n _view=default|full|csv _sort={param}
Actions (measures) relating to a Water Body {root}/so/WaterBody/{id}/measures measure.measureTier1={code} measure.measureTier2={code} measure.measureTier3={code} _limit=n _view=default|csv _sort={param}

Classifications

WhatAPIParameters
Classifications {root}/data/classification waterBody=wb inOperationalCatchment=oc inManagementCatchment=mc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} hasRFF=rff _limit=n _view=default|csv _sort={param}
Objectives {root}/data/classification-objective-outcome waterBody=wb inOperationalCatchment=oc inManagementCatchment=mc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} hasRFF=rff hasRFF.type=ty _limit=n _view=default|csv _sort={param}
Predicted outcomes {root}/data/classification-predicted-outcome waterBody=wb inOperationalCatchment=oc inManagementCatchment=mc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}

Problems, Investigations, Reasons and Measures

WhatAPIParameters
Problems {root}/data/problem waterBody=wb inOperationalCatchment=oc classification.classificationItem={code} _limit=n _view=default _sort={param}
Investigations {root}/data/investigation waterBody=wb inOperationalCatchment=oc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default _sort={param}
Reasons for not achieving good (RNAG) {root}/data/reason-for-failure waterBody=wb inOperationalCatchment=oc classificationItem={code} businessSector=bs pressureTier1=p pressureTier2=p pressureTier3=p swmi=s exists-action=true|false _limit=n _view=default|full|csv _sort={param}
Measures (actions) {root}/data/action waterBody=wb inOperationalCatchment=oc measure.measureTier1={code} measure.measureTier2={code} measure.measureTier3={code} _limit=n _view=default|csv _sort={param}

Protected areas

WhatAPIParameters
Protected areas {root}/id/protected-area waterBody=wb search=s _limit=n _view=default _sort={param}

Code lists

WhatAPIParameters
Classification items - tree view {root}/def/waterbody-classification/classification-items
Classification items - flat view {root}/def/waterbody-classification/classification-items/flat search={text}
Classification values {root}/def/waterbody-classification/classification-value search={text}
Classification certainty {root}/def/waterbody-classification/classification-certainty search={text}
Business sectors related to RNAGs - tree view {root}/def/reason-for-failure/business-sector
Business sectors related to RNAGs - flat view {root}/def/reason-for-failure/business-sector/flat search={text}
Pressures relating RNAGS {root}/def/reason-for-failure/pressure search={text}
Apportionment {root}/def/reason-for-failure/apportionment search={text}
Activities {root}/def/reason-for-failure/activity search={text}
Certainty of RNAG {root}/def/reason-for-failure/certainty search={text}
SWMI (SignificantWater Management Issue) {root}/def/reason-for-failure/swmi search={text}
Reason for alternative objectives {root}/def/reason-for-failure/reason-for-alternative-objectives search={text}
Measure tiers - tree view {root}/def/reason-for-failure/measure/tier
Measure tiers - flat view {root}/def/reason-for-failure/measure/tier/flat search={text}
Measures {root}/def/reason-for-failure/measure search={text}
Deterioration types {root}/def/waterbody-classification/deterioration-type search={text}

Data Span

WhatAPI
Years for which classifications are available {root}/data/classification/years
Years for which objectives are available {root}/data/classification-objective-outcome/years
Years for which predicted outcomes are available {root}/data/classification-predicted-outcome/years

API structure

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

Simple requests

For example fetching data from: http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.json

will return a JSON data packet such as:

{
  "@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/catchment-planning/ui/reference",
    "version": "0.1",
    "comment": "WARNING: Pre-alpha test service",
    "hasFormat": [
      "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.rdf",
      "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.ttl",
      "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.html"
    ]
  },
  "items": [
    {
      "@id": "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870",
      "characteristic": [ ...]
    }
  ]
}

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 (not yet supported).

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/catchment-planning/ui/reference",
    "version": "0.1",
    "comment": "WARNING: Pre-alpha test service",
    "hasFormat": [
      "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.rdf",
      "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.ttl",
      "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870.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.

Finally, in the case of calls which provide lists of results then any applied limit to the length of the list and offset from the start of the list will be shown in the metadata as limit and offset values, for example:

"meta": {
    "publisher": "Environment Agency",
    "licence": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "documentation": "http://environment.data.gov.uk/catchment-planning/ui/reference",
    "version": "0.1",
    "comment": "WARNING: Pre-alpha test service",
    "hasFormat": [ ...],
    "limit": 10,
    "offset" : 50
  },

Note that some endpoints impose a length limit even if one has not been 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 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. Thus, for example in the fuller version of the earlier example:

"items": [
    {
      "@id": "http://environment.data.gov.uk/catchment-planning/so/WaterBody/GB104027063870",
      "characteristic": [ ... ],
      "currentVersion": { ... },        
      "inOperationalCatchment": { 
        "@id": "http://environment.data.gov.uk/catchment-planning/so/OperationalCatchment/3499",
        ...
      },
      "inspireNotation": "GB104027063870",
      "notation": "GB104027063870",
      "type": [
        {
          "@id": "http://environment.data.gov.uk/catchment-planning/def/water-framework-directive/River"
        },
        {
          "@id": "http://environment.data.gov.uk/catchment-planning/def/water-framework-directive/WaterBody"
        },
        {
          "@id": "http://purl.org/linked-data/version#VersionedThing"
        }
      ],
      "waterbodyNotation": "GB104027063870"
    }
  ]

we can see the Water Body has a URI, the last element of which matches the water body notation (GB104027063870). This is a common pattern and when referencing items in API calls then it is often possible to just use this last element in place of the full URI.

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 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 for convenient viewing in a web browser, but all item descriptions can also return information in JSON and RDF formats (RDF/XML and Turtle). 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 HTML, JSON, CSV and sometimes GeoJSON as well as RDF formats.

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

curl -i -H "Accept: text/csv" http://environment.data.gov.uk/catchment-planning/so/WaterBody?inOperationalCatchment=3325

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
.htmltext/html
.csvtext/csv
.geosonapplication/geo+json
.ttltext/turtle
.rdfapplication/rdf+xml

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. However, in some cases a customized view is provided better suited to the CSV format and, where possible, match the data downloads provided by the Catchment Data Explorer. So a better version of the above example is:

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

Where the props are the short property names that appear in the JSON format and the value is the value that the property is requried 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, the list of all classifications (lots!) is:

We can filter that to only look at Overall Water Body classifications for a particular water body in Cycle 1 by adding the filters (spaces for readability):

Here the filter value for the cycle is a simple number whereas the value for the classficationItem is a shorthand for the full URI http://environment.data.gov.uk/catchment-planning/def/waterbody-classification/wbc_106.

If the sample filter is used twice with different values then the API will return results for both values (disjunction). For example, to get the Overall Water Body classifications for a single year/cycle for two water bodies then:

As well as filtering on exact values for properties then some endpoints (water bodies and catchments) support filtering by free text search using search={text}.

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

QueryMeaning
_view=full|..An alternative view of the items. The default view includes most of the descriptive properties and includes in-line copies of some linked items. Some APIs offer richer views (full) or occasionally more compact views. Some endpoints also support a csv view that is better suited than the default when returning as CSV data.
_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.
_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.

River Basin Districts (RBD)

River Basin Districts (RBD) are the largest units in the catchment hierarchy. They contain Management Catchments which in turn contain Operational Catchments which contain Water Bodies. The data on the RDBs themselves only comprises a name and a notation number to identify them. This notation number is the {id} element in the API calls below and may be used to represent the RDB in API filters.

WhatAPIParameters
List River Basin Districts {root}/so/RiverBasinDistrict search=x _limit=n _view=default|full
A single River Basin District {root}/so/RiverBasinDistrict/{id}
Boundary polygon for a River Basin District (as GeoJSON) {root}/so/RiverBasinDistrict/{id}/polygon
Management catchments in district {root}/so/RiverBasinDistrict/{id}/management-catchments search=x _limit=n _view=default|full
Operational catchments in district {root}/so/RiverBasinDistrict/{id}/operational-catchments search=x _limit=n _view=default|full
Water bodies in district {root}/so/RiverBasinDistrict/{id}/water-bodies search=x _limit=n _view=default|full

Management Catchments

Management Catchments are the next level down the hierarchy. They similarly just have names and notations, but also link to the RBD that contains them. Management Catchments, as well as being of type ManagementCatchment may also be one of the more specialized types: SurfaceWater, ArtificialWater or GroundWater.

WhatAPIParameters
List Management Catchments {root}/so/ManagementCatchment inRiverBasinDistrict=n search=x _limit=n _view=default|full
A single Management Catchment {root}/so/ManagementCatchment/{id}
Boundary polygon for a Management Catchment (as GeoJSON) {root}/so/ManagementCatchment/{id}/polygon
Operational catchments in Management Catchment {root}/so/ManagementCatchment/{id}/operational-catchments search=x _limit=n _view=default|full
Water bodies in Management Catchment {root}/so/ManagementCatchment/{id}/water-bodies search=x _limit=n _view=default|full

The format of the returned data in the default view is:

FieldMeaningTypeOccurs
inRiverBasinDistrictA general property for relating a resource to a containing river basin district. Used for relating catchments and water bodies to their containing RBD.RiverBasinDistrict
inRiverBasinDistrict.inspireNotationN/td>
inRiverBasinDistrict.labelA name for the inRiverBasinDistrict.rdf:langString
inRiverBasinDistrict.notationA string or other literal which uniquely identifies the inRiverBasinDistrict.
inRiverBasinDistrict.riverBasinDistrictNotationRelates a river basin district to a notation for its ID.uk-wfd:RiverBasinDistrictNotation
inRiverBasinDistrict.typeThe class or type of this inRiverBasinDistrict.rdf:Resourcemulti-valued

Operational Catchments

Operational Catchments are the next level down from Management Catchments in the catchment hierarchy. In addition to a name and notation, the link to the Management Catchment and RDB that contains them. They also link one or more Postcode Districts that overlap with them.

WhatAPIParameters
List Management Catchments {root}/so/OperationalCatchment inManagementCatchment=n inRiverBasinDistrict=n search=x _limit=n _view=default|full
A single Operational Catchment {root}/so/OperationalCatchment/{id}
Boundary polygon for a Operational Catchment (as GeoJSON) {root}/so/OperationalCatchment/{id}/polygon
Water bodies in Operational Catchment {root}/so/OperationalCatchment/{id}/water-bodies search=x _limit=n _view=default|full

The format of the returned data in the default view is:

FieldMeaningTypeOccurs
inManagementCatchmentA general property for relating a resource to a containing management catchment. Used to related water bodies and operational catchment to their containing management catchments.ManagementCatchment
inManagementCatchment.inRiverBasinDistrictA general property for relating a resource to a containing river basin district. Used for relating catchments and water bodies to their containing RBD.RiverBasinDistrict
inManagementCatchment.inspireNotation
inManagementCatchment.labelA name for the inManagementCatchment.rdf:langString
inManagementCatchment.managementCatchmentNotation
inManagementCatchment.notationA string or other literal which uniquely identifies the inManagementCatchment.
inManagementCatchment.typeThe class or type of this inManagementCatchment.rdf:Resourcemulti-valued
inRiverBasinDistrictA general property for relating a resource to a containing river basin district. Used for relating catchments and water bodies to their containing RBD.RiverBasinDistrict
inRiverBasinDistrict.inspireNotation
inRiverBasinDistrict.labelA name for the inRiverBasinDistrict.rdf:langString
inRiverBasinDistrict.notationA string or other literal which uniquely identifies the inRiverBasinDistrict.
inRiverBasinDistrict.riverBasinDistrictNotationRelates a river basin district to a notation for its ID.uk-wfd:RiverBasinDistrictNotation
inRiverBasinDistrict.typeThe class or type of this inRiverBasinDistrict.rdf:Resourcemulti-valued

Water Bodies

Water Bodies are the smallest unit in the catchment hierarchy. Each represents a unit of surface water, being the whole (or part) of a stream, river or canal, lake or reservoir, estuary or stretch of coastal water. A groundwater water body is a defined area of an aquifer with geological and hydrological boundaries to ensure consistency and avoid fragmentation.

The description of Water Bodies in the data is complicated by the need to support versioning. Between different cycles of the Water Framework Directive the precise boundary and description of a water body might vary slightly. To represent this each water body record is given a version. For each there is a single overall record which includes information such as the Operational Catchment containing it, plus summary characteristics. That overall record then links to each version (and a distinguished current version) of the water body. Each version has the same Water Body notation and for most of the API it is this version-independent notation that is used.

The specific Water Body version has additional properties including links to upstream/downstream water bodies, and associated protected areas and the hydromorphological designation (e.g. whether the body is artificial or heavily modified).

WhatAPIParameters
List Water Bodies {root}/so/WaterBody waterBody=notation type=t OperationalCatchment=n inManagementCatchment=n inRiverBasinDistrict=n search=x polygon={geojson}_limit=n _view=default|full|minimal|csv
A single Water Body {root}/so/WaterBody/{id}
A single Water Body, specific version {root}/so/WaterBody/{id}/{version}
Boundary polygon for a Water Body (most recent version, as GeoJSON) {root}/so/WaterBody/{id}/polygon
River Line geometry if the Water Body is a river (most recent version, as GeoJSON) {root}/so/WaterBody/{id}/river-line

The format of the returned data in the default view is:

FieldMeaningTypeOccurs
characteristicA measured characteristic of the water body such as it's area.wbcoptional
characteristic .characteristicIDThe characteristic being measured.Characteristic
characteristic .characteristicID .characteristicUnitThe units the characteristic is measure in.
characteristic .characteristicID .labelA name for the characteristic.characteristicID.xsd:string
characteristic .characteristicValueThe measured value.
currentVersionThe current version of the water body.WaterBodyVersion
currentVersion .competentAuthority
currentVersion .envelopeBounding box for the water body.Envelope
currentVersion .hydromorphologicalDesignationAn open domained property that indicates the Hydromorphological Designation of a water body, i.e. whether it is considered to be artificial or heavily modified.uk-wfd:HydromorphologicalDesignation
currentVersion .hydromorphologicalDesignation .labelxsd:string
currentVersion.immediateDownStreamWater bodies downstream of this one.optional
currentVersion.immediateUpStreamWater bodies upstream of this one.optional
currentVersion.inspireNotation
currentVersion.isVersionOfWaterBodyEndurant
currentVersion.labelA name for the currentVersion.xsd:string
currentVersion.ngrNational Grid Reference.
currentVersion.notationA string or other literal which uniquely identifies the currentVersion.
currentVersion.representativePointRelates a water body to a representative point. A representative point is a point in and near the middle of the water body.Point
currentVersion.typeThe class or type of this currentVersion.rdf:Resourcemulti-valued
currentVersion.versionInfo
currentVersion.waterBodyNotationRelates a waterbody to a notation for its ID.uk-wfd:WaterBodyNotation
inOperationalCatchmentA general property for relating a resource to a containing operational catchment. Used to related water bodies and operational catchment to their containing operational catchments.OperationalCatchment
inOperationalCatchment.labelA name for the inOperationalCatchment.rdf:langString

For convenience the API provides short cuts for retrieving classifications, objectives, predicted outcomes, investigations, measures and RNAGs (Reasons for Not Achieving Good) associated with the Water Body. These are all equivalent to listing the corresponding data filtered by waterBody={wb-notation}.

WhatAPIParameters
Classifications for a Water Body {root}/so/WaterBody/{id}/classifications cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}
Objectives for a Water Body {root}/so/WaterBody/{id}/objective-outcomes cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}
Predicted outcomes for a Water Body {root}/so/WaterBody/{id}/predicted-outcomes cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}
Investigations relating to a Water Body {root}/so/WaterBody/{id}/investigations _limit=n _sort={param}
RNAG (Reasons for not achieving good) relating to a Water Body {root}/so/WaterBody/{id}/reasons-for-failure businessSector=bs pressureTier1=p pressureTier2=p pressureTier3=p swmi=s classificationItem={code} exists-action=true|false _limit=n _view=default|full|csv _sort={param}
Actions (measures) relating to a Water Body {root}/so/WaterBody/{id}/measures measure.measureTier1={code} measure.measureTier2={code} measure.measureTier3={code} _limit=n _view=default|csv _sort={param}

Classifications

Classifications are methods for distinguishing the environmental condition or "status" of water bodies and putting them into one category or another. In the data each classification record links to the water body being classified, the classification item being assessed (e.g. Overall ecological status), the year and the Water Framework Directive cycle to which it applies and the value of the classification (e.g. Good). The same record structure and same API structure applies to actual classifications (assessments of past state) as well as to predicted future status and objective (status being aimed for).

The hierarchy of classification item is illustrated in the help pages. It is available in machine readable form from the API at: {root}/def/waterbody-classification/classification-items. When filtering a list of classifications for those pertaining to a specific classification item then, as usual, you can use the last elements of the URI given in that table. For example, use wbc_106 to find information on the Overall Water Body status.

If the classification value is less than Good, then there the classification may link to an RNAG (Reason for Not Achieving Good), called a reason for failure in the data itself. These in turn link to problem descriptions with associated investigations and actions (measures).

WhatAPIParameters
Classifications {root}/data/classification waterBody=wb inOperationalCatchment=oc inManagementCatchment=mc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} hasRFF=rff _limit=n _view=default|csv _sort={param}
Objectives {root}/data/classification-objective-outcome waterBody=wb inOperationalCatchment=oc inManagementCatchment=mc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} hasRFF=rff hasRFF.type=ty _limit=n _view=default|csv _sort={param}
Predicted outcomes {root}/data/classification-predicted-outcome waterBody=wb inOperationalCatchment=oc inManagementCatchment=mc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default|csv _sort={param}

The format of the returned data in the default view is:

FieldMeaningTypeOccurs
classificationCertaintyClassificationCertaintyoptional
classificationCertainty.labelA name for the classificationCertainty.xsd:string
classificationConfidencexsd:decimaloptional
classificationDeteriorationCertaintyClassificationCertaintyoptional
classificationDeteriorationCertainty.labelA name for the classificationDeteriorationCertainty.xsd:string
classificationDeteriorationTypeIf the classification represents a deterioration then this may link to a concept indicating the type of deterioration.SummaryConceptoptional
classificationDeteriorationType.labelA name for the classificationDeteriorationType.xsd:string
classificationItemThe aspect of the water body being classified.classification:ClassificationItem
classificationItem.labelA name for the classificationItem.xsd:string
classificationValueA property that relates a water body classification, classification predicted outcome or classification objective outcome observation to a classification value.ClassificationValue
classificationValue.labelA name for the classificationValue.xsd:string
classificationYearA dimension property that relates an classification observation to a year for which a classification applies.xsd:gYear
cycleA dimension property that relates a classification observation to the catchment planning cycle.uk-wfd:Cycle
cycle.notationA string or other literal which uniquely identifies the cycle.
hasRFFLinks to a recorder describing the Reason for Not Achieving Good (RNAG) and associated investigations.optional
hasRFF.labelA name for the RNAG.xsd:string
hasRFF.typeThe class or type of this RNAG.rdf:Resourcemulti-valued
typeThe class or type of this Item.rdf:Resourcemulti-valued
waterBodyA general property for relating a resource a resource to a water body. Used for relating river basin districts and catchments to water bodies.WaterBody

Examples

Find the Overall Water Body status for two water bodies for the year 2015, as assessed under cycle 2:

Find the same information for all waterbodies in a particular operational catchment:

Find all assessment of ecological status for waterbodies in an operational catchment and sort them by water body, cycle then year:

Find all assessments of ecological status for waterbodies in an operational catchment that have value poor:

Problems, Investigations, Reasons and Measures

The Problem records link different elements of the investigations and actions that can arise from a failure to achieve a good classification. They link to the classification being addressed, the investigations taking place (cause of failure, confirmation of failure, feasible measures) and to the overall status of the problem.

WhatAPIParameters
Problems {root}/data/problem waterBody=wb inOperationalCatchment=oc classification.classificationItem={code} _limit=n _view=default _sort={param}

The Investigation records linked to these problem records provide the planned and actual start and end dates for investigations and the type of the investigation.

WhatAPIParameters
Investigations {root}/data/investigation waterBody=wb inOperationalCatchment=oc cycle=c classificationItem={code} classificationYear={year} classificationValue={code} _limit=n _view=default _sort={param}

When the reason for not achieving good has been determined then an associated RNAG record will be created. This will be linked to the failing classification and to the associated problem/investigation records. The RNAG record is categorized along a number of axes - the associated activity believed to be causing it (e.g. Sewage discharage), how much of the problem is apportioned to that cause, the associated business sector and the elements that are under pressure

WhatAPIParameters
Reasons for not achieving good (RNAG) {root}/data/reason-for-failure waterBody=wb inOperationalCatchment=oc classificationItem={code} businessSector=bs pressureTier1=p pressureTier2=p pressureTier3=p swmi=s exists-action=true|false _limit=n _view=default|full|csv _sort={param}

For example to list the RNAGs associated with a specific water body:

From there you can follow links to the associated problems and investigations.

For example to list the RNAGs associated with a specific water body that relate just to Sewage discharge:

Or to list the RNAGs associated with a specific water body that have no associated measure (action):

TO list the RNAGs associated

Finally, details of measures being taken are recorded with details (dates, status, lead organization) and classified as to the types of measure. Each measure record links to the associated RNAG and from there back to the investigations, problem and original less-than-good classification.

WhatAPIParameters
Measures (actions) {root}/data/action waterBody=wb inOperationalCatchment=oc measure.measureTier1={code} measure.measureTier2={code} measure.measureTier3={code} _limit=n _view=default|csv _sort={param}

For example to find all measures associated with a water body:

The format of the returned measure data in the default view is:

FieldMeaningTypeOccurs
measureA code describing the measure.Measure
measure.measureReferenceCode
measure.measureTier1MeasureTier
measure.measureTier1.labelA name for the measure.measureTier1.xsd:string
measure.measureTier2MeasureTier
measure.measureTier2.labelA name for the measure.measureTier2.xsd:string
measure.measureTier3MeasureTier
measure.measureTier3.labelA name for the measure.measureTier3.xsd:string
reasonForFailureAn open domained property for relating a resources, typically an Investigation or a water body classification, with a reason for failure.ReasonForFailure
reasonForFailure.waterBodyA general property for relating a resource a resource to a water body. Used for relating river basin districts and catchments to water bodies.WaterBody
reasonForFailure.waterBody .currentVersionWaterBodyVersion
reasonForFailure.waterBody .currentVersion.labelA name for the reasonForFailure.waterBody.currentVersion.xsd:string
reasonForFailure.waterBody .inOperationalCatchmentA general property for relating a resource to a containing operational catchment. Used to related water bodies and operational catchment to their containing operational catchments.OperationalCatchment
reasonForFailure.waterBody .inOperationalCatchment .inManagementCatchmentA general property for relating a resource to a containing management catchment. Used to related water bodies and operational catchment to their containing management catchments.ManagementCatchment
reasonForFailure.waterBody .inOperationalCatchment .inManagementCatchment.inRiverBasinDistrictA general property for relating a resource to a containing river basin district. Used for relating catchments and water bodies to their containing RBD.RiverBasinDistrict
reasonForFailure.waterBody .inOperationalCatchment .inManagementCatchment .inRiverBasinDistrict.labelrdf:langString
reasonForFailure.waterBody .inOperationalCatchment .inManagementCatchment.labelrdf:langString
reasonForFailure.waterBody .inOperationalCatchment.labelrdf:langString

Protected Areas

The data includes information on Protected Areas associated with water bodies. In some cases, this information includes a seeAlso link to a source of more information on the protected area:

WhatAPIParameters
Protected areas {root}/id/protected-area waterBody=wb search=s _limit=n _view=default _sort={param}

For example, to find protected areas associated with either of two water bodies:

Code lists

Many elements of the above data are classified or categorized using controlled sets of terms. The descriptions of these terms is included in the data and available through the API. Each term or code in a code list is identified by a URI but typically has an associated short notation and a descriptive label. In most cases the last element of the URI can be used in API calls to filter records pointing to such codes.

When the code lists form a hierarchy then it is convenient to be able to get the whole hierarchy at once as a JSON tree structure to enable applications to navigate the hierarchy. The default API calls follow this model. However, it's also helpful to have a flat view of the hierarchical code lists (with links to the narrower concepts) to allow for text search and for returning in CSV format. In those cases we provide a /flat version of that API.

WhatAPIParameters
Classification items - tree view {root}/def/waterbody-classification/classification-items
Classification items - flat view {root}/def/waterbody-classification/classification-items/flat search={text}
Classification values {root}/def/waterbody-classification/classification-value search={text}
Classification certainty {root}/def/waterbody-classification/classification-certainty search={text}
Business sectors related to RNAGs - tree view {root}/def/reason-for-failure/business-sector
Business sectors related to RNAGs - flat view {root}/def/reason-for-failure/business-sector/flat search={text}
Pressures relating RNAGS {root}/def/reason-for-failure/pressure search={text}
Apportionment {root}/def/reason-for-failure/apportionment search={text}
Activities {root}/def/reason-for-failure/activity search={text}
Certainty of RNAG {root}/def/reason-for-failure/certainty search={text}
SWMI (SignificantWater Management Issue) {root}/def/reason-for-failure/swmi search={text}
Reason for alternative objectives {root}/def/reason-for-failure/reason-for-alternative-objectives search={text}
Measure tiers - tree view {root}/def/reason-for-failure/measure/tier
Measure tiers - flat view {root}/def/reason-for-failure/measure/tier/flat search={text}
Measures {root}/def/reason-for-failure/measure search={text}
Deterioration types {root}/def/waterbody-classification/deterioration-type search={text}

For example, to search the classification items code list for items mentioning oxygen:

This returns two items Dissolved Oxygen and Biochemical Oxygen Demand (BOD). Selecting the first of these takes us to: {root}//def/waterbody-classification/wbc_69. The last element of the URI wbc_69 can then be used in filters to retrieve information on the Dissolved Oxygen classifications of water bodies. For example:

Or to get a CSV version: