Listings 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

Listing URL Generation

Listings content is available in multiple resolutions in both cropped and un-cropped versions see reference table. All content is served from the https://lid.zoocdn.com/ domain. HTTP 200 status is returned for successful requests and HTTP 404 for unavailable content. Requests to http://lid.zoocdn.com/ will be redirected to the secure domain.

To construct an image URL, select your chosen resolution and substitute the attribute placeholders as appropriate. For cropped images the URL path is

and un-cropped images have a URL path

Floorplan images should always use the un-cropped version. An optional :p suffix can be added to the URL to request a WebP image format.

The resulting URL

• https://lid.zoocdn.com/<width>/<height>/<filename>
• https://lid.zoocdn.com/u/<width>/<height>/<filename>
• https://lid.zoocdn.com/<width>/<height>/<filename>:p

Listings API Spec