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": "Hydrology API for sub-daily data",
    "license": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "licenseName": "OGL 3",
    "publisher": "Environment Agency",
    "version": "2.0.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": "Hydrology API for sub-daily data",
    "license": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "licenseName": "OGL 3",
    "publisher": "Environment Agency",
    "version": "2.0.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:

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:

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 stations which include observations about temperature 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:

For example, supply the parameter min-dateTime=12/03/2021 to query hydrology readings recorder after 12/03/2021.

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. value=(1.4..3.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.

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:

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.

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