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.