Comparables API
Authentication
We use the OAuth2 Client Credentials flow to authenticate and authorize requests to our APIs.
More information on how this work is available here and here
To make requests to our APIs you need to get an access token to use to pass to the API.
Getting a token
Get the client_id and client_secret. We will provide this to you.
Request Access: If you don’t have credentials yet, simply reach out to us- we’re here to help.
You will have to concatenate the client_id, ‘:’ and the client secret and base64 encode it, for example:
echo '{ "client_id":"Test_client","client_secret":"Test_secret" }' \\
| jq "." \\
| jq -r '(.client_id + ":" + .client_secret) \\
| @base64'
VGVzdF9jbGllbnQ6VGVzdF9zZWNyZXQ=
Either client_id and client_secret or the base64 encoded concatenation should be stored somewhere securely.
Then make POST request to https://data.services.zoopla.co.uk/oauth2/token. (Note this is not /v1/ as this is reused by other API’s as well and won’t match the version numbers of the comparables api if they increment)
Pass Authorization header consisting of the concatenation of credentials (from above).
curl -s --data-urlencode 'grant_type=client_credentials' \
-H 'Authorization: Basic VGVzdF9jbGllbnQ6VGVzdF9zZWNyZXQ=' \
'https://data.services.zoopla.co.uk/oauth2/token' \
| jq -r '.'
{ "access_token":"eyJraWQiOiJ5M0...",
"expires_in": 3600,
"token_type": "Bearer"
}
From this result, get the access token.
Then makes all other API requests using the access token:
curl -s -H "Authorization: Bearer $access_token" \
https://data.services.zoopla.co.uk/v1/comparables/123456 \
| jq "."
You can also check the payload of the token. There are libraries to do that or use jwt.io or just base64 decode the second part after splitting on ‘.’
# Decode the token
decoded=$(echo "$access_token" | jq -R 'split(".") | .[1] | @base64d | fromjson')
# To get something like this payload:
{ "sub":"13qampsrrb7vra7ql5v0tp0oej",
"token_use": "access",
"scope": "comparables_api/",
"auth_time": 1694531487,
"iss": "https://cognito-idp.eu-west-2.amazonaws.com/eu-west-2_sbjmetE1t",
"exp": 1694535087,
"iat": 1694531487,
"version": 2,
"jti": "9ed74ace-27a5-497b-9862-a0dd71e473a6",
"client_id": "13qampsrrb7vra7ql5v0tp0oej"
}
# exp here will tell you when the token will expire.
Notes about tokens
- Tokens are valid for an hour
- Multiple requests to the token endpoint in a short time will give the same (cached) response. Therefore, please do not rely on the expires_in field which will always show 3600 (one hour), as this may not always be accurate Instead please use the exp timestamp inside the token
- You can request a new token several minutes before the expiration to mitigate risk of interruption. We would suggest getting a new token every 20 minutes or so and reusing it
Once you have the comparables returned you can use the uprn and theListings API to get more information on the property including photos and floorplans where available.