Environmental
Research
Group
–
Application
Programming
Interface
Introduction
Welcome to the ERG API. We hope you find it easy to use and useful. This is version 1.2 of the API.
Who we are
The Environmental Research Group (ERG), part of the School of Biomedical Science at King’s College London, is a leading provider of air quality information and research in the UK. We can be contacted on the email address erg‐[email protected] .
What we are providing
The main resource we are making available is air quality monitoring data available for London, which has been recorded automatically since 1993. We also have predicted grids of pollution levels at any location in London for annual and current measurements.
Air quality is a complicated subject, and it can be worth reading up about it before trying to interpret data. A good place to start would be the guide on the London Air website.
Terms and conditions
The use of the API is subject to the Open Government License version 2, which can be found at http://www.nationalarchives.gov.uk/doc/open‐government‐licence/version/2/.
Below is an example attribution statement for use in websites, applications or documents:
This information has been obtained from the Environmental Research Group of Kings College London (http://www.erg.kcl.ac.uk), using data from the London Air Quality Network
(http://www.londonair.org.uk). This information is licensed under the terms of the Open
Government Licence.
The feeds provided are still undergoing development, and may change in future. We will try to keep this to a minimum.
The API is intended to be used from one fixed IP address. If this feed is to be used by applications or from client side web pages, then the users server should act as a proxy, and cache data where appropriate.
Please also tell us about anything you make using our API. This will help us make sure we do not break anything when we update it, and will allow us to show how it is being used, helping us to keep the service properly supported.
Monitoring API General Notes
All monitoring data requests start with the url http://api.erg.kcl.ac.uk
The latest version of this documentation can be found at
http://api.erg.kcl.ac.uk/AirQuality/Documentation/pdf.
We aim to explain the idea behind each feed rather than specify the exact syntax, which instead can be found in the API automatic information.
This resource implements a REST interface. Requests are case sensitive, and particular care should be taken to make sure that “London” starts with an upper case L. Do not add trailing slashes where not specified. Currently all requests use the HTTP “GET” verb, as the API only returns data at present.
Most responses are in XML by default, but you can get a Json response by appending /Json to the feed. We also have some csv feeds (/csv) and pdf feeds (/pdf).
We have arranged our API into objects in basic groups. Each object should always return data with the same syntax. Most objects take variables, which will change the amount of data returned.
Monitoring
API
feeds
Information
This group contains base information about what monitoring sites there are, what pollutants are measured, what the air quality objectives are, health advice etc. This information is often useful to help interpret measured and monitored data.
Groups
Our monitoring sites are organised in groups, mostly based on area. This feeds allows you to see which groups exist. Many of the other feeds use the group name as part of the request.
Index Health Advice
This request matches an air quality index to health advice for the General population and At‐risk individuals. This is important information to turn pollution levels in to health advice. If an air quality index is supplied then just the matching records are returned.
AirQualityBand Description of overall banding, one of Low, Moderate, High or Very High
LowerAirQualityIndex, UpperAirQualityIndex Lower and upper air quality indexes of that Band. The index runs from 1 to 10.
Population Who the advice applies to, either At-risk individuals or General
Population
Advice Text giving advice for the population when it is exposed to the level of pollution.
Monitoring Local Authorities
This lists the local authorities that have air quality monitoring with ERG. This can be done by supplying a GroupName e.g. London.
Monitoring Sites
This lists the monitoring sites where air quality is measured. This details basic details such as where the site is, when it was open, and what was measured there. This can be selected by GroupName e.g. London, or by Local Authority Name (LaName).
Species
This lists the commonly monitored pollutants (“Species”), along with their code, a description and the health effect. This can list all of them, or a chosen species.
Objectives
This lists the details of annual air quality objectives.
Hourly Data
Hourly Monitoring Index
The returns the latest hourly air quality monitoring indexes requested. This can be selected by local authority or by group. The feed lists a number of local authorities, each of which have a number of sites, and each of those has a number of species (pollutants). The health effect of these indexes can be found in the IndexHealthAdvice feed. The following explains what some of the attributes returned mean:
TTL: This stands for Time To Live, and is the number of minutes that the data supplied is valid for.
SiteType: A text description of the location of the site compared to pollution sources, one of “Kerbside”, “Roadside”, “Suburban”, "Urban Background", “Rural” and “Industrial”. This has a profound effect on the air quality levels recorded at the site.
SiteCode: Code used to refer to the site, as the name may change. SiteName: Name of the site, more understandable by people.
SpeciesName Longer name for the species SpeciesCode Short code for the species
AQIndex The index of the air quality from 1-10, or 0 for no data. This can be mapped to health advice using the feed IndexHealthAdvice.
IndexSource Either "Measurement" or “Trigger”. Trigger is a type of prediction of pollution levels, and on the Londonair website we display triggers with a different symbol.
DataEnd The end date and time of the index, including the timezone. The start date and time would be the hour before.
Hourly Map
This returns a list of the hourly maps available, along with meta data about when they were created and when they apply from.
TTL Time to live, how long in minutes the data is valid for. SpeciesCode Short code for the nowcast species
CalculateDate When the nowcast was calculated StartDate When the nowcast period starts EndDate When the nowcast period ends
MeasurementDateLong Nice text version of the measurement date
Ratio The ratio of the current nowcast to the annual average. Less than one is a lower then average nowcast, high than 1 is a higher than average nowcast.
MeasurementDate Last date of the measurements included in the nowcast calculation.
NowcastLink Base URL of the nowcast REST feed
Daily Data
Daily Monitoring Index
This lists the chosen days monitoring indexes. This can be select by group, local authority or site, and also includes the date. The return is very similar to the format of the hourly index.
Latest Daily Index
This returns data in the same format as the daily monitoring index, but for the latest day that has been calculated. The date of the bulletin can be found near the start of the feed.
Annual Data
Annual Monitoring Objective
This lists compliance to annual monitoring objectives by monitoring sites. This can be selected by group, local authority or site. Each local authority has a number of sites, and each of these list the objectives that site has measured. Each objective is for a particular year and objective, and there can be more than one objective per species.
Annual Map
This returns a list of the annual maps available, along with meta data about when they were created and when they apply from. The format is very similar to the hourly maps format.
Data
This gives basic measurements numbers as a time series dataset. The data can be selected by site, or by site and species, and involves the use of start and end dates. It can be returned in xml, json or csv formats, The csv format can be very useful for inputting into existing mapping tools. The DateTime value is always in GMT. There are also some options to return the data in “wide” format, where each datetime has one entry and all the values are listed
on that row, very like a spreadsheet. The standard return is one row per measurement, which is more similar to a database format.
Geographic API General Notes
The geographic API is still experimental and subject to change in the future. All geographic requests start with the url http://webgis.erg.kcl.ac.uk Automatic information on the feeds can be found at
webgis.erg.kcl.ac.uk/ArcGIS/rest/services And help on the interface can be found at:
http://webgis.erg.kcl.ac.uk/ArcGIS/SDK/REST/index.html?overview.html This resource implements a REST interface amongst others.
The REST interface returns data in a selection of formats, including Json, xml, csv and pdf.
Geographic Data Feeds
Current PM10 Particle and Nitrogen Dioxide air quality index levels at a location
http://webgis.erg.kcl.ac.uk/arcgis/rest/services/{SpeciesCode}now/MapServer/identify?geo metryType=esriGeometryPoint&geometry={Longitude}%2C{Latitude}&sr=&layers=&time=&l ayerTimeOptions=&layerdefs=&tolerance=1&mapExtent=‐
0.5%2C+51.45%2C0.5%2C+51.55&imageDisplay=600%2C550%2C96&returnGeometry=false &maxAllowableOffset=&f=pjson
This request takes a SpeciesCode (Currently NO2 or PM10), latitude and longitude, with all other parameters being set to defaults. The mapExtent and imageDisplay values must be set even though returnGeometry is set to false. The response has the attributes:
"Class value" The air quality index (1-10). The can be used to reference health advice using the IndexHealthAdvice feed
"Pixel value" The measurement in micrograms per meter cubed (ug/m3)
Images for use in display
There is an Esri api that allows maps layers to be added to a google map. It is added to a google map using the statement:
dynamicMap = new
esri.arcgis.gmaps.DynamicMapServiceLayer("http://webgis.erg.kcl.ac.uk/ArcGI S/rest/services/NO2now/MapServer", null, 0.75, dynmapcallback);
We know this utilises some of the REST API calls to generate images at the correct location and scale, but we have not yet had time to find out exactly which call it uses.
