API Guidance
The programmatic user is given the ability to access the data deli public API after they are done selecting their assets (per their subscription quota) and access token creation. The access token and pre-selected assets are significant prerequisites for using the data deli public API.
The Data deli API provides information based on two significant parameters namely, Metrics and Postcodes. At this point, it is assumed that the programmatic users have already selected their assets, including the metrics and postcode (postal area), and also generated an access token required to query the data deli public API.
Endpoint and Parameter
The Data deli public API possesses two major endpoints:
These endpoints are responsible for communicating with the data deli public API, more details below.
1. Fetching your metrics
GET /api/v1/my-metrics
The first endpoint enables users to get the list of metrics they have already selected during asset management in order for them to be able to choose and apply the pre-selected metrics when querying the public API using the second (2) endpoint. One main reason for providing them with this endpoint is to help the user avoid applying unknown metric parameters when accessing the API.
The snippet on the right shows an example of the response a user receives when they make a GET request to the first endpoint to retrieve their pre-selected metrics.
N.B. This endpoint requires no query parameters or path parameter when making the GET request, however the API require the apiKey header parameter which contain the generated access token.
Header Parameters:
apiKey: parameter for passing the current or active access token.
- type: string
- required: true
Response Object
{
"data": [
{
"name": "Background Noise",
"slug": "background_noise",
"metricYears": [
2019,
2018,
2020,
2021,
2022
]
},
{
"name": "Conservation Areas",
"slug": "conservation_areas",
"metricYears": [
2018
]
}
],
"version": "1.0.0",
"attribution": "http://data-deli.test/waluel.com",
"valid_as_of": "2022-09-28 16:06:30"
}Considering the API response illustrated in the snippet, the data property is an array of objects whereby each object is a single representation of the client’s pre-selected metrics. The programmatic user is required to choose the slug or a group of slugs (depending on whether the user needs information on all metrics) and also a year from the “metricYears” array. These two selected parameters (slug and metricYear[year]) will be required when accessing the second (2) API endpoint.
2. Search For Data
POST /api/v1/data/search
The second endpoint is the last endpoint through which the programmatic user can attain the information they need. The second (2) endpoint is accessible by making an HTTP POST request together with two major parameters namely, metrics and postcodes.
Header Parameters:
apiKey: parameter for passing the current or active access token
- type: string
- required: true
Body Parameters:
metrics:
The metrics parameter takes an array of objects and each object holds two properties (key-value) which are metricId and year. The metricId and the year were the values extracted as slug and year respectively from the first (1) endpoint. N.B. when the value for the year property is null or empty, data deli fetches the latest year for the given metric(s).
- type: array
- required: true
postcodes:
The postcodes parameter accepts an array of postcodes that the programmatic users are required to fill in. N.B. If the postcodes parameter is empty, data deli API will return an error message indicating that the postcodes parameter can not be a null or an empty array.
The second block of code in the snippet gives an example of the operation needed to successfully query the second (2) endpoint.
- type: array
- required: true
Response Object
{
"status": "success",
"data": [
{
"geoUnitId": 1,
"identifier": "BR1 1AA",
"data": {
"details": {
"Longitude": "0.015415",
"Latitude": "51.401546",
"X": "1715.964796",
"Y": "6692632.222",
"Area Guide": "https://kirby.wa-insight.com/area-guides/bromley-town-centre"
},
"metricsData": [
{
"id": 15,
"metricName": "Background Noise",
"metricDescription": "Walulel's Background Noise Metric estimates the level of background noise residents of your neighbourhood can expect",
"metricType": "internal",
"showMarker": false,
"data": {
"year": 2021,
"summary": [
{
"dataIndex": 0,
"label": null,
"dataset": [
{
"id": 1,
"name": "Decibel Level (dB)",
"actual": 57.45,
"displayActual": "55.0-59.9",
"min": 55,
"mid": 62.45,
"max": 75,
"step": 0.2,
"quintiles": [
{
"name": "Quintile 1",
"value": 160571
},
{
"name": "Quintile 2",
"value": 19056
},
{
"name": "Quintile 3",
"value": 0
},
{
"name": "Quintile 4",
"value": 8999
},
{
"name": "Quintile 5",
"value": 5314
}
],
"descriptor": "Decibel Level (dB) description",
"unitMeasurement": "db"
},
{
"id": 2,
"name": "Noise Band (Pentile)",
"actual": 1,
"displayActual": "1",
"min": 1,
"mid": 1,
"max": 5,
"step": 0.4,
"quintiles": [
{
"name": "Quintile 1",
"value": 160571
},
{
"name": "Quintile 2",
"value": 19056
},
{
"name": "Quintile 3",
"value": 8999
},
{
"name": "Quintile 4",
"value": 5314
},
{
"name": "Quintile 5",
"value": 1158
}
],
"descriptor": "Noise Band (Pentile) description",
"unitMeasurement": "db"
}
]
}
]
}
},
{
"id": 17,
"metricName": "Conservation Areas",
"metricDescription": "Walulel's Conservation Area Metric lets you know whether your neighbourhood falls within a Conservation Area, as designated by your local planning authority",
"metricType": "internal",
"showMarker": false,
"data": []
}
],
"mapMetricsData": [],
"externalData": [],
"travelTimeData": []
}
}
]
}HTTP Errors and their meaning
Every public API has its dos and don’ts and Data Deli is not an exception. Clients are prone to making mistakes when querying public APIs, hence the table below illustrates potential errors based on HTTP status codes and their implications.
| STATUS CODE | MEANING |
|---|---|
| 400 |
|
| 401 |
|