Using the Bathing Water Quality Application

Using this application you can:

  • look up past and current water quality information about a bathing water
  • drill down into the water quality data
  • create a personalised summary of today's bathing water quality situation

Finding a Bathing Water

Search box

Using the Search Box

1. Start typing the name of a bathing water(beach), a local authority or a county screenshot showing use of search box to search for bathing water

Or you can type in a full post code

2. As you type in the search box the names of all bathing waters, local authorities and counties that contain the search term so far will appear

3. At any point you can:

  • click on one of the bathing water names to make a choice
  • click on the 'show results on map' icon to show where the results are on the map
  • click on a bathing water 'globe' icon to see where it is on the map

The Map

Using the Map

1. Zoom into the area you are interested in on the map. screenshot showing use of map to search for bathing water

  • you can use the map controls, mouse scroll wheel or touch screen drag and zoom

2. Click on the icon of a bathing water you want to select.

3. If you want to see the water quality information for that bathing water, click 'show profile' in the pop-up box.

Bathing Water Quality Profile Pages

Bathing Water Quality Information

Bathing water profile pages give summary information about a bathing water, its water quality and its management. screenshot of bathing water quality profile page showing key features.

  1. Basic information about the bathing water
    • The name and county of the Bathing Water
    • Description of the beach
    • Photograph of the beach
    • The official European Bathing Water Directive water quality classification for the current year (Note that the first official classification will not be made until the end of the 2015 season)
  2. Alerts for the day and the result of the latest water quality measurement
    • Pollution Risk Forecast indicates if there is a prediction that there might be a significant increase in pollution due to heavy rain. Clicking on the date/time link will take you to the information about that alert.
    • Abnormal situations tells you if there are any pollution incidents that might affect bathing water quality
    • The result of the latest water quality sample measurements - indicates if the latest test sample had bacterial concentrations are above the nominal thresholds for the 'satisfactory' classification of the Bathing Waters Directive Classification.
  3. Annual water quality assessments
  4. Site Details: Provides a range of information about the bathing water.
    • Local authority: the local authority for the bathing water
    • Year of designation: the year that the bathing water was designated
    • Water quality monitored: The period during the year when the bathing water is monitored
    • Water sampling point location: Geographic co-ordinates for the bathing water. These can be used by GPS or Satellite Navigation systems to locate the bathing water.
    • Map links: links to external maps of the location using Google Maps, Bing Maps, OpenStreetMap
    • Twitter feed: the twitter ID of the bathing water, if there is one
    • Nearby bathing waters: lists the five nearest bathing waters by distance as the crow flies
    • Link to this page: clicking on 'QR Code or Web Widget' opens up a dialogue box that has a QR code with the URL for this bathing water that can be used in print materials and a link to the Web Widget designer for this bathing water.
  5. Location Map and Features

    The map shows the location and the bathing water quality related features at the bathing water. Features include:

    • bathing water sampling location feature icon Bathing water sampling location point on the bathing water
    • river or stream intersection feature icon River or stream intersects the bathing water
    • emergency or storm overflow feature icon Emergency or storm overflow (see glossary)
    • surface water outfall feature icon Surface water outfall (see glossary)
    • treated sewage feature icon Treated sewage works outfall
    • disused feature icon Feature that is no longer active
  6. Detailed Bathing Water and Water Catchment Information. This section gives information about issues that affect the water quality and includes:
    • Catchment description
    • Step changes
    • Investigations statement
    • Pollution, its management and forecasting
    • Information about how Natural Resources Wales is working with water companies, local authorities, the farming community, industry, and others
    • Information about algae

Get the Data Behind the Water Quality Information

Getting to the Water Quality Data

There are three ways to get to the water quality data pages for a bathing water: screenshot of links to water quality data pages for a bathing water from a bathing water quality profile page.

  1. The water quality data link on the main menu
  2. Clicking on the date/time link of the latest measurement
  3. Clicking on the year of the annual water quality assessments

Water Quality Data Pages

There are five tabs on the Water Quality Data section

screenshot of interface tabs on water qualtiy data page

Graphs – showing the water quality data

screenshot of data plots of bacterial concentrations on the graphs tab of water quality data section. This tab shows a graphical summary of the results of the bathing water sample measurements for the selected years.

There are two types of graph:

Detailed Sample History

screenshot of data table in detailed sample history tab of water quality data section. This tab shows a table of the sample results for the selected period for this bathing water.

Abnormal Situations

screenshot of data plots of abnormal situations tab of water quality data section. This tab shows a table of all of the abnormal situations for a bathing water. An abnormal situation is a pollution event, due to sewage or animal faeces, which has the potential to affect bathing water quality.

Pollution Risk Forecast History

screenshot of pollution risk forecast history tab of water quality data section. This tab shows a table of the Pollution Risk forecasts for a bathing water for the period selected.

Download Data

screenshot of download data tab of water quality data section. This tab gives links to:

  • Download bathing water quality data and profile information for use in spreadsheets or other data analysis software
  • Use the data in web and other software applications via an API (Application Programming Interface)

More detailed instructions are given on the Using the API help page

Summary of Today's Bathing Water Quality Situation

The bathing waters overview page allows you to create a personalised summary of today's bathing water quality situation screenshot of bathing water overview link in top right page menu.

screenshot of bathing water overview selection instructions. Follow the instructions on the bathing water overview page to create a summary of the current situation for a personalised list of bathing waters. It includes any pollution risk forecasts and abnormal situations, as well as the previous four years of water quality classifications and last four sample measurements.

screenshot of bathing water overview selection list of results. You can bookmark or save this page once created and return to it at any time to see the latest situation at your chosen group of bathing waters.

Bathing Water Quality

Natural Resources Wales takes up to twenty water samples at each of Wales' designated bathing waters during the bathing water season between May and September each year. A classification for each bathing water is calculated annually, based on samples from the previous four years. These classifications are, from best to worst:

A sample tells us the quality of the water at that specific time, but water quality can fluctuate considerably even over the course of one day. In each sample we test for bacteria that indicate whether there is faecal matter in the water. The bacteria we test for are:

When more of these bacteria are present in a bathing water there are greater risks to bathers' health. The standards we use are specified in the Bathing Water Directive and are based on World Health Organisation research which recorded the incidence of gastrointestinal disease (stomach upsets) in people bathing in waters of differing bacterial concentrations.

We have given the data for each of the samples a symbol to indicate whether a sample is over the threshold indicated by the “poor” classification or better.

  • small graphic indicating acceptable quality indicates acceptable water quality
  • small graphic indicating unacceptable quality indicates low water quality

Water quality can change on a day to day basis. This may be due to:

  • Heavy rain or tides washing pollution into the water that flows into a bathing water from the surrounding catchment. Daily Pollution Risk Forecasts (PRF) alert users to this possibility for many bathing waters.
  • On rare occasions abnormal situations can occur which may affect water quality. For example a pollution incident, or emergency discharge from the sewerage system.

Both of these kinds of alerts are shown by a warning triangle icon Warning triangle for poor water quality on the main map on the home page, profile pages for individual bathing waters, and the bathing waters overview.

Some bathing waters can be affected by Combined Sewer Overflows (CSO). About 70% of the sewers in Wales are combined systems. This means they collect runoff as well as sewage and wastewater from homes and businesses. The CSOs act as a safety valve during heavy rainfall. Unless these controlled discharges into local watercourses are permitted, there is a risk that sewage could flood homes and businesses following heavy rain overwhelming sewers.

At present this website does not provide alerts for CSO incidents. However we support the voluntary CSO alerts scheme set up by Surfers Against Sewage and water companies. More information can be found on the Safer Seas Service website.

Water Quality Assessments

Designated bathing waters in Wales now have tougher water quality targets to achieve; the new standards are approximately twice as strict as they were prior to 2015.

The assessment process is based on the Bathing Water Directive, which was fully implemented into English law on the 24 March 2015. It replaces the old 1976 directive and regulations. Its provisions are being phased in and the more stringent standards were introduced in 2015.

From the end of the 2015 bathing water season all designated bathing waters will be classified as excellent, good, sufficient or poor. The classifications are based on a detailed statistical analysis of the sample measurements taken over a four year period unless a step change in quality has occurred because of an improvement action such as new sewerage infrastructure. In such cases, only data collected since the action will be assessed.

The analysis groups bathing waters into classifications based on the probability that most of the time concentrations of Escherichia coli (EC) or Intestinal enterococci (IE) will be below classification thresholds (95% or 90% probability depending on the classification – see below). The criteria for coastal bathing waters and inland bathing waters are different. The thresholds for classifications are as follows:

Classification Thresholds Confidence level
Coastal Bathing Waters
Excellent EC: ≤250 cfu/100ml ; IE: ≤100 cfu/100ml 95th percentile
Good EC: ≤500 cfu/100ml ; IE: ≤200 cfu/100ml 95th percentile
Sufficient EC: ≤500 cfu/100ml ; IE: ≤185 cfu/100ml 90th percentile
Poor means that the values are worse than the sufficient
Inland Bathing Waters
Excellent EC: ≤500 cfu/100ml ; IE: ≤200 cfu/100ml 95th percentile
Good EC: ≤1000 cfu/100ml ; IE: ≤400 cfu/100ml 95th percentile
Sufficient EC: ≤900 cfu/100ml ; IE: ≤330 cfu/100ml 90th percentile
Poor means that the values are worse than the sufficient
Key EC: Escherichia coli, IE: Intestinal enterococci, cfu: Colony Forming Units

 

For planning purposes Natural Resources Wales uses unofficial projected classifications based on these standards for samples collected during years before 2015. These classifications use data collected using different analytical methods for data prior to 2012 and are therefore approximations of what the actual classifications would have been.

Projected classifications are included on this website to show the history of water quality at each bathing water. The official classifications before 2015 are based on the old standards and can be found here . The first official classification under the new regime will be published towards the end of 2015.

The use of standardised symbols for the four classes, which all countries in the EU have to use at bathing waters across Europe, will help people make informed choices on where to swim when home and abroad. The symbols are available at the EU web site and will be used on this site once the first official annual classification is available at the end of the 2015 season.

If water is classified as poor, then the symbol for "poor" together with a sign showing advice against bathing must be displayed in the following season. So a "poor" result in 2015 will require relevant signs to be posted by local councils in 2016. A sign displaying a "poor" classification and advice against bathing does not mean a beach is closed.

Short term pollution

Short term pollution (STP) is bacterial pollution that occurs at a bathing water and is not expected to last for more than 72 hours. Provisions to deal with STP are designed to help protect the public from predictable pollution of short duration. Compliance samples taken during events which are defined as STP may be disregarded from the compliance dataset.

Natural Resources Wales issues pollution risk forecasts (PRF) at bathing waters where water quality is known to be reduced after heavy rainfall. PRF warnings identify where there is an increased risk of short term pollution due to run-off from rainfall. STP events are those STPs which have warning signs displayed in the vicinity of the bathing water when a pollution risk warning is issued. They coincide with a routine water sample and an additional sample has to be collected by Natural Resources Wales after the STP event to confirm its end. This confirmation sample cannot be used for classifications.

Disregarding samples from the compliance dataset can only take place if they were collected during an STP event, and only up to 15% of samples used in the classification data may be disregarded. This discounting assessment is made at the end of each monitoring season and is shown in the data by the discounted field.

Projected classifications

Classifications from before 2015 are projected because they use data collected using different analytical methods prior to 2012. They are therefore approximations of what the actual classifications would have been. The first official classification under the new regime will be published towards the end of 2015.

1976 Bathing Water Directive
This directive was introduced in 1976 to protect and improve bathing water quality; with the aim of protecting human health and facilitating recreational use of natural waters.
Abnormal Situation
A pollution event, due to sewage or animal faeces, which has the potential to affect bathing water quality. If this occurs Natural Resources Wales will notify the local council who will put up signs warning the public that this has occurred and compliance sampling will be suspended. The signs will come down when water is clear of pollution.
Algae (seaweed and phytoplankton)
Algae are types of plant which can be very small like pinpoints floating in the sea or larger like seaweed growing on the sea bed.
Bathing Water Quality
The quality of a bathing water is a measure of how clean it is.
Bathing water sample point
The point at a bathing water where we take water samples, chosen to be at the place where most people bathe.
Bathing Water Season
The bathing water season in Wales is 15 May to 30 September. This period is when we expect the majority of people to use the bathing waters. Water quality is regularly monitored during the season.
Bathing Water Directive
The (revised) Bathing Water Directive (2006/7/EC) was fully implemented in English law on 24 March 2015. It updates the old Bathing Water Directive and regulations. The overall objective of the revised Directive remains the protection of public health whilst bathing, but it also offers an opportunity to improve management practices at bathing waters and to standardise the information provided to bathers across Europe. The revised directive standards are much more stringent than those for the old Directive.
Bathing Waters Directive Classification
The Bathing Water Directive has standards for four classes of water quality:
  • "excellent" – the highest, cleanest class
  • "good" – pollution effects are small or rare
  • "sufficient" – can be affected by pollution
  • "poor" – advice is not to bathe in this water due to pollution levels
Blue Flag

The Blue Flag is a voluntary eco-label awarded to over 3800 beaches and marinas in 46 countries across Europe, South Africa, Morocco, Tunisia, New Zealand, Brazil, Canada and the Caribbean.

The Blue Flag works towards sustainable development of beaches and marinas through strict criteria dealing with water quality, environmental education and information, environmental management, and safety and other services.

The Blue Flag Programme is owned and run by the non-government, non-profit organisation The Foundation for Environmental Education (FEE).

Body of water
A volume of water, such as part of a river, lake, stream or the sea.
Catchment
The catchment of a bathing water is the land area that drains rainfall into the water.
Coastal Bathing Waters
There are two types of bathing waters – coastal and inland bathing waters. The Directive has different standards for these types of waters.
Colony Forming Units (cfu)
This is an estimate of the number of bacteria in a sample of water. This is done by counting the number of colonies (groups) of bacteria growing on a filter through which the sample has been passed.
Competent Authority
A competent authority is the organisation that has responsibility for monitoring and protecting a designated bathing water. In England this is the Environment Agency, in Scotland Scottish Environmental Protection Agency, Wales Natural Resources Wales and Northern Ireland the Department of Environment Northern Ireland.
Compliance with current Bathing Water Directive
Each bathing water receives an annually assessed water quality classification. We assess the number of certain types of bacteria which may indicate the presence of pollution, mainly from sewage or animal faeces. Escherichia coli (EC) and Intestinal enterococci (IE) are bacteria that indicate the presence of faeces. An increase in the concentrations of these bacteria indicates a decrease in water quality.
Contamination
Impurity or pollution.
CSO – Combined Storm Sewage Overflow
Overflow pipes designed to relieve pressure on sewerage systems during periods of high rainfall and so prevent flooding. Overflows allow rainwater and diluted sewage (usually screened to remove solids), to bypass sewage treatment works and flow directly into rivers and coastal waters.
CSO incident
When a CSO spills unexpectedly due to an incident such as a blockage or broken pipeline.
Cyanobacteria
A type of bacteria that grown in water and get their energy from the sun, like plants. These sometimes rapidly multiply and form blooms and scums in fresh-water, these sometimes are poisonous.
Designated Bathing water
Parts of the sea or inland waters in the UK have been designated for people to swim in. Bathing waters become designated if a large number of people use them. What a large number is depends on the position and size of the beach and bathing water. The Bathing Water Directive sets standards for these waters to protect public health. Designation in Wales is made by the Department of Environment Food and Rural Affairs (Defra). These waters are sampled by Natural Resources Wales and results of analyses are reported annually to the European Commission.
Diffuse pollution
Pollution from land use activities (urban and rural) that are spread across a catchment, and which do not start from a point such as, industrial discharges or municipal sewage effluents.
Disused outfall
A pipe that is no longer used to discharge waste water.
DNA tracing technique or MST
Microbial Source Tracking (MST) for bathing water analysis. This technique analyses sequences of genetic code from particular types of gut bacteria or directly from animal DNA.  These analyses help to determine whether the source of the pollution has human, farm animal, bird or other origins.
Effluent
Liquid waste or sewage discharged to the environment
Emergency or storm overflow
A pipe in a sewerage system which only discharges during emergencies or when there is a significantly large rainstorm which is a risk of flooding the sewer system.
Escherichia Coli (E.coli)

E. coli is one of the indicators that is being used to measure water quality.

E. coli are a group of organisms found in the intestines of animals and humans and survive for a while in the environment when excreted. Many types of E. coli are not harmful but some such as E. coli 0157 can directly cause illness. The presence of the bacteria indicates that human or animal excretions may be present in bathing water and could contain other potentially harmful organisms that could cause illness.

Occasionally, usually during heavy rainfall, soil containing E. coli bacteria is washed into, rivers, streams, lakes, or groundwater leading to bathing waters, and if found, E. coli bacteria indicates that harmful bugs could be present.

Faecal coliforms (FC) and faecal streptococci (FS)
These bacteria were used to assess bathing water quality prior to 2012. They are types of bacteria found in sewage and animal faeces whose presence in high numbers indicates poor water quality. Although not necessarily disease-causing themselves, high levels of these indicator bacteria at a site indicate that disease causing organisms may be present.
Faecal Matter
Poo from animals and birds
In-season measurement
A sample taken and analysed during the bathing season, normally 15th May to 30th Sept
Intestinal Enterococci (IE)

Enterococci are one of the indicators under the directive used to measure water quality.

Enterococci are found in the intestines of animals and humans although some types are environmental in origin . The presence of the bacteria indicates that human or animal excretions may be present in bathing water alongside other potentially harmful organisms that could cause illness.

Occasionally, usually during heavy rainfall, soil containing Enterococci bacteria is washed into, rivers, streams, lakes, or groundwater leading to bathing water and the presence of intestinal enterococci can indicate that harmful bugs can be present.

Investigations
Investigations into the reasons for changes in water quality
Macroalgae
Algae made up of more than one cell, such as seaweed.
Misconnections (Also called wrong connections)
Misconnections of foul sewage pipes into surface water drains are a significant source of urban diffuse pollution in those areas where a separate drainage system is used. Misconnections can happen when domestic plumbing has been connected into surface water drains instead of the foul sewer.  This means untreated dirty water goes directly into the environment without receiving treatment.
Monitoring
Each bathing season (15 May to 30 September in England and Wales, 1 June to 15 September in Scotland and Northern Ireland), water quality inspectors from the relevant environment agency take samples at every designated bathing water to monitor their quality. These are analysed and the results are posted on our websites.
Not sampled
Indicates that the bathing water was closed during the bathing season.
Permit
A discharge permit to set the design criteria or discharge water quality standards of a sewerage system to protect water quality.
Phytoplankton
Tiny plants found in water.
Pollution
Any contaminants that can reduce water quality for example sewage from a sewage works or sewer system, poo from cows washed off a field into a stream, dogs' and birds' poo washed down a gutter into the sea. For bathing waters, we concentrate on pollution which increases the amount of bacteria in the water.
Pollution Risk Forecast
Pollution risk forecasts are predictions made based on the amount of rainfall, that there will be a significant increase in pollution. We can make this prediction at some waters not other because only some waters are susceptible to rain driving pollution into the water.
Profile
A bathing water profile is a document containing information on a designated bathing water. Profiles are a requirement of the revised Bathing Water Directive. They are available through the Bathing Water Quality Application.
Sea outfall pipe
A pipe which conveys and discharges treated wastewater or storm water and sewage into coastal or estuarine waters.
Sewage
Waste water from toilets and washing, draining from homes and businesses.
Sewage treatment works outfalls
A sewage works outfall is where the treated effluent from a sewage works comes out.
Signage
Signs to inform the public are a requirement of the Bathing Water Directive. From 2012 signage is required to inform the public of the state of the bathing water quality at each designated bathing water.
Sluice gate
Valve or gate fitted to a sluice (channel that carries a rapid current of water) to control the rate of flow of water.
Spill frequency
The frequency with which an overflow discharges. The definition of what a discharge is in terms of flow volume or time period is under debate.
Step Change
A step change in the context of bathing waters is where a significant action has taken place to improve the water quality, so rather than use a 4 year set of data to assess compliance we can use data from the time that the improvement action took place.
Surface water outfall
A surface water outfall is a pipe that discharges rainwater which has fallen on the land and runs into drains and gutters before being discharged.
Surface water runoff
Rainwater that flows off land including, roofs, roads, pathways, driveways, hard standings and car parks.
Ultra Violet (UV) treatment
Ultraviolet light is passed through treated sewage effluent to reduce the numbers of micro-organisms.
Water Company
Water companies supply water services in Wales.  Some are water supply only companies and some are combined water and sewerage companies.
Water Quality Assessment
This is where we look at the results of our analysis of samples taken at the bathing water and decide what the classification of the water should be using statistical calculations. These calculations give us a measure of what the average quality is over four years.
WFD – Water Framework Directive
European Union legislation Water Framework Directive (2000/60/EC) - establishing a framework for European Community action in the field of water policy.
Year of Designation
The year in which a bathing water was officially designated by Defra.

Using the bathing water data API

The web Application Programming Interface (API) is an easy to use tool to select and retrieve data. It is useful for building applications that use bathing water profile and bathing water quality data. It is suitable, for example, for building a web page that displays a dashboard of bathing waters in a particular region or for building a table to include in a report.

The API can be accessed using a Web browser or any other program that can retrieve web pages. For example, clicking on this link. will list, in a new window or tab, all of the bathing waters in Cornwall.

The previous link retrieved the data formatted as an HTML page. This xml link will retrieve the same data formatted as XML, and this json link will retrieve it in JSON format. Other formats, e.g. comma-separated values (CSV) and Turtle are also supported.

As with any web based API, the interface consists of patterns of web addresses or URLs. In this introduction we will look at some example patterns to illustrate how the API can be used. There is a comprehensive description of the structure of the data and the URL patterns of the API, which can be found in the bathing water quality reference documentation.

A basic example

Let's look in more detail at the parts of the link used above:

http://environment.data.gov.uk/doc/bathing-water.json?_view=basic&_pageSize=200&district=http://data.ordnancesurvey.co.uk/id/7000000000043750

This URL consists of an endpoint URL and some query parameters. The endpoint URL here is http://environment.data.gov.uk/doc/bathing-water.json. The endpoint URL defines the broad category of data to be returned, in this case a list of one or more bathing waters. The .json on the end of this endpoint URL specifies the format of the data to be returned; JSON in this case.

Query parameters modify the data that is returned. Query parameters can be used to filter the data, limit the number of results, and sort the data. Let's look in more detail at the query parameters used in the example:

  • _pageSize=200: the number of results to return. The default is 10. The upper limit is 200.
  • _view=basic: which properties of each bathing water to return. There are a number of predefined views. The basic view is the smallest, containing just the name and type of each bathing water. We will see other predefined views below, as well as how to extend them.
  • district=http://data.ordnancesurvey.co.uk/id/7000000000043750: this is a filter. It says only return bathing waters whose district property has the value http://data.ordnancesurvey.co.uk/id/7000000000043750. That value is the Ordnance Survey's linked data identifier for Cornwall. Thus the filter says to only retrieve bathing waters located in Cornwall.

The API need not only be accessed through a web browser. Here is an example of using that URL to retrieve data not using a browser. The program wget is commonly found on linux systems (and is also available on OSX and Windows computers). Wget is used to retrieve data from a URL from the command line, or a script. Here, it is used to retrieve JSON format data into a file:

wget -O data.json "http://environment.data.gov.uk/doc/bathing-water.json?_view=basic&_pageSize=200&district=http://data.ordnancesurvey.co.uk/id/7000000000043750"

Using a browser to develop API queries

Most the of the functionality of the API is exposed via the web pages it generates. For example, when data is retrieved as a web page, there is a drop down menu listing all the data formats available. Another menu shows the views available on an endpoint. The menu to the right of a property value supports sorting and filtering values.

One way to develop a URL to retrieve data is to retrieve an example using the Web interface, using the menus available to select, filter and sort the data as required. The URL in the browser bar at the end of this process can then be copied and used in an application.

Other endpoints

The http://environment.data.gov.uk/doc/bathing-water endpoint is known as a list endpoint because it returns data about a list of items. Generally, to retrieve information about a particular item, simply append a '/' character, followed by the identifier for the item to an appropriate list endpoint.

For exmample, the identifier for the Kingsand bathing water is ukk3101-26520. Data about Kingsand can be retrieved by appending the identifier to the URL for the bathing water list endpoint to produce http://environment.data.gov.uk/doc/bathing-water/ukk3101-26520

Other endpoints in the data that may be of interest include:

A comprehensive list of endpoints can be found in the reference documentation.

Interpreting the returned data

The data returned by the API includes metadata as well as the data requested. In the XML formatted data the data requested is included in the <items> and <item> elements. Similarly, in the JSON formatted data, the "items" and "item" members hold the requested data. The other elements and members hold metadata.

Views

The data returned consists of data items and their properties. The value of a property might be a data value such as a string or an integer, or another item, which can also have properties.

Views are used to select which properties are included in the returned data. In our example above, we specified that we wanted to use the basic view. The basic view is the simplest view and just includes type and label properties. If no view is specified, as in this request:

http://environment.data.gov.uk/doc/bathing-water.json?_view=basic&amp;_pageSize=200&amp;district=http://data.ordnancesurvey.co.uk/id/7000000000043750

then a default view is used. The easiest way to see which views are available for a particular endpoint is to use the view drop down menu in the web page for the end point.

There are some built in views that are common to all end-points:

  • basic: a minimal view with just type and label properties
  • description: all the properties of an item
  • all: like a description view, but adds the label properties of any sub-items

If none of the predefined views are suitable, then it is possible to augment a predefined view by adding to properties that are returned from the API. We can add a _properties query parameter to the URL. This parameter takes a comma-separated list of properties to include in the view. Here, for example, we have extended the basic view by adding the yearDesignated property:

http://environment.data.gov.uk/doc/bathing-water?_view=basic&_properties=yearDesignated&_pageSize=200&district=http://data.ordnancesurvey.co.uk/id/7000000000043750

To retrieve properties of sub items, chain the property names together with a dot character. For examle, we can add the latest compliance assessment by adding the chain of properties latestSampleAssessment.sampleClassification.label to the view, like this:

http://environment.data.gov.uk/doc/bathing-water?_view=basic&_properties=yearDesignated,latestRiskPrediction.riskLevel.label&_pageSize=200&district=http://data.ordnancesurvey.co.uk/id/7000000000043750

If we had only added the property latestRiskPrediction, we would have retrieved the URI for that prediction object but none of its properties. We can instead use the dot notation to specify a chain of properties to be retrieved. The example uses this to retrieve the human friendly name of the risk level of the latest short-term pollution prediction. A star character, * denotes all properties. To retrieve all of the properties of the latest pollution prediction, including the label, use the path latestRiskPrediction.riskLevel.*.

The names of all the available properties can be found in the bathing water quality reference documentation.

Filters

We have seen one use of a filter so far in our example The district=http://data.ordnancesurvey.co.uk/id/7000000000043750 parameter restricts the results to bathing waters in Cornwall. In this example, we are specifying the exact value of a property. We can also specify the minimum value of a property by adding min- to its property name, or max- to specify the maximum value of a property. Property chains can be used too.

For example, to select all the bathing waters west of Penzance, we specify a maximum value for the longitude:

http://environment.data.gov.uk/doc/bathing-water?&_pageSize=200&max-samplingPoint.long=-5.53552896653342

Sorting and paging

The _sort parameter can be used to sort results, while the _pageSize parameter limits the number of results returned, which can be use with the _page parameter to select a particular batch of results. For example:

http://environment.data.gov.uk/doc/bathing-water?_sort=samplingPoint.lat&_pageSize=10&_page=2

selects the third batch (the first one is page zero) of ten bathing waters, ordered from south to north.

To invert the sort order, and sort from north to south, insert a '-' before the sort property like this:

http://environment.data.gov.uk/doc/bathing-water?_sort=-samplingPoint.lat&_pageSize=10&_page=2

Limitations

While a lot can be done with the API, there are some things that require a full query language such as SPARQL. The one that is most often encountered is that you can't have an 'or' operation in a filter. Its not possible, for example, to select bathing waters that are west of Penzance OR east of London.

What next

As mentioned above, more detailed information about the bathing water API can be found in the bathing water quality reference documentation.

This API is implemented by an open source tool called Elda. See the Elda documentation for more comprehensive documentation about what it can do.