Introduction

Zoopla.co.uk are pleased to provide a number of separate API methods for developers to work with a number of data sets, whether its property listings, transactional sold price data, or Zoopla.co.uk's proprietary Zed-Index of current area property values or Zoopla.co.uk Estimates, the current estimated value of an individual property. 

The methods for accessing the data are via standard API methods and protocols. All requests to the API (version 1) should be made using the GET method of the HTTP protocol. Access using other methods at this time is not guaranteed to produce the results described in the documentation provided here.

Requests, areas, parameters and disambiguation

All requests to the API (version 1) should be made using the GET method of the HTTP protocol. Access using other methods at this time is not guaranteed to produce the results described in this document.

Standard input parameters

There are several standard input parameters that are accepted by all API method calls, some of which are mandatory and some of which are optional. These are detailed below.

Parameter name StatusDescription
api_key Mandatory The API key provided to you by Zoopla.co.uk. This parameter is mandatory for every method call.
session_id Optional A session identifier provided by the get_session_id API method call, required for some method calls.

In addition to the standard input parameters thare are also several location related parameters that area used to determine a particular location a method should use. The parameters listed below will be recognised and used for this purpose. Several parameters may be specified and by doing so the resulting location will be more accurate. Different methods may only use a subset of these input parameters depending on their function.

Parameter name Description
area Arbitrary area name, or postcode.
street Name of street to locate.
town Name of a town to locate.
postcode Full or partial postcode.
county The name of a county.
country The name of a country.
latitude Exact latitude of a location, must be used in conjunction with longitude and will take priority over other parameters specified. Valid values are in the interval [-90,90].
longitude
Exact longitude of a location. Valid values are in the interval [-180,180].
lat_min Lower bound of a latitude range, must be used in conjunction with lat_max, lon_min and lon_max. Valid values are in the interval [-90,90].
lat_max Upper bound of a latitude range, must be used in conjunction with lat_min, lon_min and lon_max. Valid values are in the interval [-90,90].
lon_min Lower bound of a longitude range, must be used in conjunction with lat_min, lat_max and lon_max. Valid values are in the interval [-180,180].
lon_max Upper bound of a longitude range, must be used in conjunction with lat_min, lat_max and lon_min. Valid values are in the interval [-180,180].
output_type The actual area type to restrict the location request to - postcode, outcode, street, town, area or county. For instance, specifying a value for "postcode" (or a postcode within the "area" parameter) above and then a value of "town" for this parameter will use the town that the postcode is within, not the postcode itself. Note that the same occurs for latitude/longitude searches; providing an exact location with an output type of "postcode" will use the postcode during the request, not the latitude/longitude provided.

Note that not all API methods support all of the area restriction parameters - notably property_listings, property_agents, and zoopla_estimates are the only methods to support lat_min, lat_max, lon_min and lon_max.

Standard output parameters

In a similar vein a standard set of output parameters will be generated that contain information about the actually matched location according to the input parameters and where the result set relates to.

Parameter name Description
area_name Display location of the street Name of street to locate.
street Name of street to locate.
town Name of a town to locate.
postcode Full or partial postcode.
county The name of a county.
country The name of a country.
bounding_box The approximated bounding box or single latitude and longitude value (ie. minimum and maximum are the same) for the provided area, with the following key/value pairs:
Key name Description
latitude_min The latitude coordinate for the top-left corner of the bounding box.
longitude_min The longitude coordinate for the top-left corner of the bounding box.
latitude_max The latitude coordinate for the bottom-right corner of the bounding box.
longitude_max The longitude coordinate for the bottom-right corner of the bounding box.

Disambiguation

Due to the nature of the addresses and locations searching for street name or town will inevitably result in several matches and the need to disambiguate between them. Under these circumstances a parameter "disambiguation" will be returned along with the generated output that contains a list of matching areas that can be searched on. The response data will contain information related to the assumed area. XML example:

<response>

    <disambiguation>Whitechapel, Devon</disambiguation>

    <disambiguation>Whitechapel, Lancashire</disambiguation>

    <disambiguation>Whitechapel</disambiguation>

    <!-- rest of response -->

<response>

By providing one of the disambiguation area names in full as the "area" parameter you can then ensure you are searching the correct area. Should one of the disambiguation areas match your search term exactly you can pre-pend a "+" to the area name to choose this area, e.g. "+whitechapel".

Spelling suggestions

As well as disambiguation we also attempt to offer a spelling suggestion in those cases where the location you requested could not be found, but had a similar spelling to a known location. This suggestion will appear in a parameter "suggestion" along with the standard "unknown location" response. XML example when searching for "stok":

<response>
    <suggestion>stoke</suggestion>
<!-- rest of response -->
</response>

Output format

Rather than using a parameter to request a specific output format (ie. ?OutputFormat=XML) the default assumed output format will be XML and others can be requested using a file extension, for example using a ".js" suffix would produce JavaScript output. Also recognised is ".xml" which outputs XML.

XML output

The root element for all XML output is "response" (example below) and therefore all output parameters will be a child of this element and translated into XML form. All arrays will be converted into multiple elements (see "array_element" below, which as an array data structure would have 4 elements) and all associative arrays (or hashes) will be converted into elements with sub-elements to represent the keys of the associative array.

<response>

        <array_element>One</array_element> 

        <array_element>Two</array_element> 

        <array_element>Three</array_element> 

        <array_element>Four</array_element> 

        <hash_element> 

            <key1>One</key1> 

            <key2>Two</key2>

            <key3>Three</key> 

        </hash_element> 

<response>

JSON output

All JSON output will translate arrays and associative arrays into their equivalent JavaScript forms directly, without a root element. Example:

{ 

    "array_element": [ "One", "Two", "Three", "Four" ], 

    "hash_element": { 

        "key1": "One", 

        "key2": "Two", 

        "key3": "Three" 

    }    

} 

Error handling

When an error occurs during a request we will be able to use the an appropriate HTTP response code to handle according to the table below (note some of these may not be required but have been included regardless):

HTTP response code Description of response
200 - OK The requested method was successful and the response indicates the expected result (if any).
400 - Bad Request The request that was made could be satisfied as the parameters provided were not sufficient to produce a valid response.
401 - Unauthorized The API key could not be recognised and the request is not authorized.
403 - Forbidden The requested method is not available for the API key specified.
404 - Not Found A method was requested that is not available in the API version specified.
405 - Method Not Allowed The HTTP request that was made requested an API method that can not process the HTTP method used.
500 - Internal Server Error An error occurred on the server that could be not be recovered from nor reported. In this case no output will be generated.

Error details

When an error occurs some output may still be generated, in which case the output can be of use to determine the exact error that occurred and whether it should be addressed on the client side. The name of the output key containing the error code is "error_code" and the text for the error is "error_string":

<response>

    <error_code>1</error_code>
    <error_string>Insufficient arguments</error_string>

<response>

Comments and feedback

Where appropriate such as for deprecated functionality or alpha versions of the API being used a "comments" field should be returned with each data result set including sufficient details to describe that the data being returned, or the method being offered may change in the future. For example:

<response>

    <comments>This version of the API is for testing only, do not use in a production environment.</comments>

<response>