Open Data API Docs

Active Places Open Data API

The Active Places Open Data API can be used to include site and facility data within your own websites and applications. Instructions on how to use the API can be found by expanding the sections below.

To receive email notifications relating to data and website enhancements, including advanced notice of schema changes, please register with the Active Places Power website (via the homepage).  

Authentication

The Active Places Open Data API endpoints do not require authentication.

Call Limits

Requests made to the Active Places Open Data API and downloads of the Active Places CSV and JSON files are limited to ensure a consistent performance is maintained for all users.

The rate limit for the CSV and JSON download is 2 requests per 60 seconds.
The rate limit for the API is 120 requests per 60 seconds.

If you exceed the rate limit, a 429 (Too Many Requests) response code will be returned.

This API is intended to be used by a third party to retrieve site data to store themselves and then to regularly update their copy of the data with any subsequent changes made in Active Places Power. The endpoint conforms to the Openactive Realtime Paged Data Exchange 1.0 specification.

Examples of Using the API

The next "10" sites that have changed since the modified value of "9500000" was recorded:
https://api.activeplacespower.com/api/v1.1/sites?afterChangeNumber=9500000&limit=10

Parameter Required Data Type Accepted Values Description
afterChangeNumber no 64-bit integer a positive integer value Each update to the database will increment the change number. The API returns all changed records with a change number greater than the number entered. Defaults to 0.
limit no integer 1-100 The number of sites to return per page. Defaults to 10.

Response Code Meaning
200 Success
400 Bad Request due to invalid parameters
429 Too Many Requests made within 1 minute
500 Internal API Error

Response

The sites will be returned as an array of items followed by the next field, which provides the API call to be used to retrieve the next page of records if there are any. A link to the OpenData license is also included. Please note that the first few hundred sites returned will be deleted records.


    

Each item will contain the following fields:

  • id - the unique Site ID. This can be used to reference the site throughout the Active Places website.
  • state - updated or deleted. A deleted site will not have any data.
  • kind - the type of record. This API will only return "site".
  • modified - the timestamp id of when this site was modified. This can be used as the afterChangeNumber parameter.
  • data - the full site data record in JSON format or null for deleted sites.

An Example Usage Scenario

A client application calls the API starting with an afterChangeNumber of 0 and limit of 100 and is returned the first 100 records. The application then uses the next field to return the next 100 records. This continues until there are no more records available and the next field is empty. The client application now has a completely up-to-date copy of all the site records. At this point the modified property of the final record in the list is stored in the application. The next time the client wants to update the site data they start the first request with the stored last modified number as the afterChangeNumber so only the records that have since changed will be returned.

A simplified example set of API calls could be:

  • ApiUrl?changeNumber=0&limit=100 which returns changes 1-100
  • ApiUrl?changeNumber=100&limit=100 which returns changes 101-200
  • ApiUrl?changeNumber=200&limit=100 which returns changes 201-300

The site data is now complete and the modified property of the final site record (300) is retained in the client application.

Over the following week another 80 sites are updated within Active Places Power. These need to be reflected within the client application so the following request is made to the API to only return records that have changed since the client last checked:

  • ApiUrl?changeNumber=300&limit=100 which returns changes 301-380

The modified number of 380 is now stored ready to check for any new changes.

The Site API returns the complete record for a site in json format.

Examples of Using the API

The site record for site Id "1206727":
https://api.activeplacespower.com/api/v1/opendata/sites/1206727

The final segment of the url is the unique SiteId of the site to return. The SiteId can be found by searching within Active Places Power or by using one of the search APIs.

Parameter Required Data Type Accepted Values Description
SiteId yes 32-bit integer a positive integer value The unique Id of a site. Path Parameter rather than a query parameter.
prettify no boolean true or false Formats the json with additional spacing so it is easier to read. Defaults to false.

Response Code Meaning
200 Success
404 No site matches the SiteId provided
429 Too Many Requests made within 1 minute
500 Internal API Error

Search for sites by name and/or postcode and optionally filter the results by the types of facilities the site provides. The first page of results will be returned. Each summary result will contain a link to the full site record.

Examples of Using the API

Sites with "river" in their name and a postcode beginning with "PL23":
https://api.activeplacespower.com/api/v1/opendata/sitesearch?sitename=river&postcode=PL23

Sites in the "EX1" postcode area that have a "Grass Pitch" facility:
https://api.activeplacespower.com/api/v1/opendata/sitesearch?postcode=EX1&facilityTypeIds=5

Page "2" of page size "10" sites (assuming there are at least 20 results) in postcode area "TA1" with "Indoor Tennis or Outdoor tennis or Squash Courts":
https://api.activeplacespower.com/api/v1/opendata/sitesearch?postcode=TA1&facilityTypeIds=4,13,17&page=2&pageSize=10

Sites that have a "Grass Pitch" facility and also sites that have an "Artificial Grass Pitch" of type "Long Pile Carpet" in the "TA1" postcode area:
https://api.activeplacespower.com/api/v1/opendata/sitesearch?postcode=TA1&facilityTypeIds=5&facilitysubtypeids=8003

Parameter Required Data Type Accepted Values Description
siteName yes - unless postcode is provided string text of maximum length 80 characters Returns all sites with a name or alias partially matching the text entered. The text will need to be encoded if searching using characters such as &.
postcode yes - unless siteName is provided string a full postcode or just the first half (outcode) Returns all sites with a postcode matching the postcode or outcode entered. The outcode is the part of the postcode before the space. A bad request will be returned if the postcode or outcode is not valid.
facilityTypeIds no integer array a comma-separated list of valid Ids Filters the sites by the type of facility they offer. Id values should be separated by a comma. E.g. 1,2,3. A list of facility type Ids can be found in the Sport Data Model link in the footer of this page. Defaults to no types being filtered out.
facilitySubTypeIds no integer array a comma-separated list of valid Ids Filters the sites by the type of facility they offer. Id values should be separated by a comma. E.g. 1001,2001,3001. A list of facility sub-type Ids can be found in the Sport Data Model link in the footer of this page. Defaults to no subtypes being filtered out.
includeClosed no boolean true or false Include sites that have closed in the results. Defaults to false.
page no 32-bit integer a valid number If the pageSize is less than the total number of matching sites returned then only the first page of records will be returned. The page parameter can then be used to return the next page. Defaults to 1.
pageSize no 32-bit integer a valid number The total number of results to return. If the site count is greater than pageSize then the page parameter can be used to return more results. Defaults to 10.
prettify no boolean true or false Formats the json with additional spacing so it is easier to read. Defaults to false.

Response Code Meaning
200 Success
400 Bad Request due to invalid parameters
429 Too Many Requests made within 1 minute
500 Internal API Error

Response

The search results will be returned in the form of a site count followed by an array of items containing summaries of the matching sites.


    
  • siteCount - The total number of matching sites.
  • items - an array containing the search result data objects.
  • licence - a link to the open data licence.

Each data item will contain the following fields:

  • id - the unique Site Id. This can be used to reference the site throughout the Active Places website.
  • name - the name of the site.
  • aliases - an array of aliases the site may also be known by.
  • address - an object containing the address of the site.
  • easting - the easting associated with the site's location.
  • northing - the northing associated with the site's location.
  • latitude - the latitude associated with the site's location.
  • longitude - the longitude associated with the site's location.
  • localAuthorityCode - the OS code associated with the local authority the site is within.
  • localAuthorityName - the local authority the site is within.
  • opendataUrl - a link to the full site record in json format.
  • siteDetailUrl - a link to the open data page for the site.
  • facilities - an array of facility summary objects for the site.

Each facility will contain the following fields:

  • id - the unique facility Id. This can be used to reference the facility throughout the Active Places website.
  • facilityType - an object representing the type of facility. It contains an id and name.
  • facilitySubType - an object representing the sub-type of the facility type. It contains an id and name.
  • operationalStatus - the current status of the facility. A list of possible statuses can be found in the Sport Data Model link in the footer of this page.

Search for sites by specifying a map coordinate and a search radius. If a postcode is entered then the centre point of the postcode will be used. The results can optionally be filtered by the type of facility a site provides.

Examples of Using the API

All sites within "1km" of Easting "530268" and Northing "179461":
https://api.activeplacespower.com/api/v1/opendata/sitespatialsearch?easting=530268&northing=179461&radius=1000

"Health and Fitness Gyms" within "1km" of Easting "530268" and Northing "179461":
https://api.activeplacespower.com/api/v1/opendata/sitespatialsearch?easting=530268&northing=179461&radius=1000&facilitytypeids=2

"Junior Football 11v11" and "Adult Football Grass Pitches" within "1km" of postcode "E20":
https://api.activeplacespower.com/api/v1/opendata/sitespatialsearch?postcode=E20&radius=1000&facilitysubtypeids=5001,5002

Parameter Required Data Type Accepted Values Description
postcode no string a full postcode or just the first half (outcode) Returns all sites within the radius of the postcode's centre point. The outcode is the part of the postcode before the space. A bad request will be returned if the postcode or outcode is not valid.
easting no - unless northing is specified decimal a valid decimal number Used with a northing to provide a map point to search from. Any sites within the radius of the coordinate will be returned.
northing no - unless easting is specified decimal a valid decimal number Used with an easting to provide a map point to search from. Any sites within the radius of the coordinate will be returned.
latitude no - unless longitude is specified decimal a valid decimal number Used with a longitude to provide a map point to search from. Any sites within the radius of the coordinate will be returned.
longitude no - unless latitude is specified decimal a valid decimal number Used with a latitude to provide a map point to search from. Any sites within the radius of the coordinate will be returned.
radius no 32-bit integer number from 10-50000 Search radius in metres. Any sites within this distance of the coordinates entered will be returned. Defaults to 10,000 (10km).
facilitySubTypeIds no integer array a comma-separated list of valid Ids Filters the sites by the type of facility they offer. Id values should be separated by a comma. E.g. 1001,2001,3001. A list of facility sub-type Ids can be found in the Sport Data Model link in the footer of this page. Defaults to no subtypes being filtered out.
includeClosed no boolean true or false Include sites that have closed in the results. Defaults to false.
page no 32-bit integer a valid number If the pageSize is less than the total number of matching sites returned then only the first page of records will be returned. The page parameter can then be used to return the next page. Defaults to 1.
pageSize no 32-bit integer a valid number The total number of results to return. If the site count is greater than pageSize then the page parameter can be used to return more results. Defaults to 10.
prettify no boolean true or false Formats the json with additional spacing so it is easier to read. Defaults to false.

Response Code Meaning
200 Success
400 Bad Request due to invalid parameters
429 Too Many Requests made within 1 minute
500 Internal API Error

Response

The search results will be returned in the form of a site count followed by an array of items containing summaries of the matching sites.


    
  • siteCount - The total number of matching sites.
  • items - an array containing the search result data objects.
  • licence - a link to the open data licence.

Each data item will contain the following fields:

  • id - the unique Site ID. This can be used to reference the site throughout the Active Places website.
  • name - the name of the site.
  • aliases - an array of aliases the site may also be known by.
  • address - an object containing the address of the site.
  • easting - the easting associated with the site's location.
  • northing - the northing associated with the site's location.
  • latitude - the latitude associated with the site's location.
  • longitude - the longitude associated with the site's location.
  • localAuthorityCode - the OS code associated with the local authority the site is within.
  • localAuthorityName - the local authority the site is within.
  • opendataUrl - a link to the full site record in json format.
  • siteDetailUrl - a link to the open data page for the site.
  • facilities - an array of facility summary objects for the site.

Each facility will contain the following fields:

  • id - the unique facility ID. This can be used to reference the facility throughout the Active Places website.
  • facilityType - an object representing the type of facility. It contains an id and name.
  • facilitySubType - an object representing the sub-type of the facility type. It contains an id and name.
  • operationalStatus - the current status of the facility. A list of possible statuses can be found in the Sport Data Model link in the footer of this page.