Nestoria
The easiest way to find UK property
Home >

Nestoria API - Technical Details

Use of the API:
Please note that your use of the API must follow the conditions listed in the overview.

Current Version:
The current API version is '1.14'. The API should be considered as beta - although we will do our best to retain backwards compatibility this might not always be possible. Please see the change log below. Requests to older versions of the API will fail with an error message advising you to upgrade.

Libraries:
There are currently three libraries that you can use to access the API:
We would also love to see a library for Ruby. Please get in touch if you have written your own library, and we will gladly list it here.

Content:
We currently support property listings for Germany, Italy, Spain and the United Kingdom.

Protocol:

API calls are made using HTTP GET The results of the API calls are returned in the body of the HTTP response either as XML or JSON. Requests should go to different servers depending on the country of listings data desired:

countryserver
Germany http://api.nestoria.de
Italy http://api.nestoria.it
Spain http://api.nestoria.es
UK http://api.nestoria.co.uk

Example Request:

An example request would be (white space inserted for clarity):

    http://api.nestoria.co.uk/api
      ? action   = echo
      & encoding = json
      & foo      = bar
  

Example Response:
The example request above would result in the following response (encoded using JSON, formatting added for display purposes):
      {
        "request" : {
          "action" : "echo",
          "country" : "uk",
          "encoding" : "json",
          "foo" : "bar",
          "language" : "en",
        },
        "response" : {
          "action" : "echo",
          "country" : "uk",
          "created_http" : "Thu, 06 Jul 2006 10:59:26 GMT",
          "created_unix" : 1152183566,
          "encoding" : "json",
          "foo" : "bar",
          "language" : "en",
          "status_code" : 200,
          "status_text" : "OK",
          "version" : 1.14
        }
      }
  

The result is split into two parts - the request and the response. The request is a copy of the request that was sent after all the defaults have been filled in and any bad values stripped out. This is the actual request that was used to create the response.

The response part contains the data generated. For the 'echo' action all it does is echo back all of the request parameters - making this useful for testing. There are several fields that are added to the response that are always present:

      status_code: The HTTP status code.
      status_text: The code as text.
      
      created_http: When the results were created in HTTP format.
      created_unix: The same but in unix form (seconds since epoch).
  

The request, the status codes and the time-stamps are in the results so that it is easier for you to just save the content of the HTTP response to a cache and still have all the information you might need.

Common Arguments:
These arguments apply to all API calls:
    action:   The name of the API methods, e.g. 'echo'
    version:  The API version - allows for backward compatibility. Optional
    encoding: How you would like the results encoded, 'xml' or 'json'
    pretty:   If set the JSON response will be pretty printed
    callback: name of function to wrap the JSON in (see below)
  
API methods:
  • echo: simply echos back the request. Intended to be used in testing and debugging.
  • keywords: returns a list of valid keywords that can be used for querying.
  • metadata: search the database for aggregated or 'meta' data based on location.
  • search_listings: search the database for listing based on location and filter the results.
Echo:
This is a simple API method. Anything sent in the request is echoed back in the response. This is only really useful for testing and debugging.

Search Listings:
Search our database for listings. To do a search you need to specify a location, either as a place name, a bounding box with coordinates or a centre point. You can then filter the results by price, bedrooms etc. You must specify if you want listings that are for sale or to let.

These are the arguments that you can pass:

    # where to search: EITHER
    place_name: 'Chelsea'                      a place name, post code, tube station, etc.
    
    # OR
    south_west: 'lat,lng'                      the SW point of a bounding box
    north_east: 'lat,lng'                      the NE point of a bounding box

    # OR
    centre_point: 'lat,lng'                    the centre point for a search 
                                               (with default radius of 2km)

    # OR
    radius: 'lat,lng,num[km|mi]'               centre point with specific radius 
                                               in km (kilometres) or mi (miles)
                                               note that the 'km' or 'mi' is not optional
    # OR
    guid: 'guid'                               A unique identifier for a single property 
                                               (which can be viewed in previously-returned results)
                                               The 'place_name' argument is required when using this argument.

    guid: 'guid,guid,guid'                     To retrieve several properties, separate GUIDs by commas. 
                                               
    
    # options:
    number_of_results:  10                     defaults to 20, capped at 50
    page: 5                                    Jumps to page 5 of returned results
    
    # filters to narrow the results:
    listing_type:  'rent' or 'buy' or 'share'  defaults to 'buy'
    property_type: 'all', 'house' or 'flat'    defaults to 'all'
    
    price_max:   'max' or number               defaults to 'max'  
    price_min:   'min' or number               defaults to 'min'
    
    bedroom_max: 'max' or number               defaults to 'max'  
    bedroom_min: 'min' or number               defaults to 'min'
    
    # for api.nestoria.es requests you may also filter 
    # by size in square metres

    size_max: 'max' or number                  defaults to 'max'  
    size_min: 'min' or number                  defaults to 'min'

    # sorting the results 
    # if no sort parameter is requested results are sorted by 
    # "Nestoria Rank" our proprietary relevance algorithm.

    sort: 'bedroom_lowhigh'  or 'bedroom_highlow' # by number of bedrooms
          'price_lowhigh'    or 'price_highlow'   # by price 
          'newest'           or 'oldest'          # by date
          'random'                                # random


    has_photo:  1                               defaults to 0
    updated_min:1220155200                      UNIX timestamp (UTC) 

        
    keywords: 'garden'                         comma separated list of valid keywords 
    keywords_exclude: 'lower_ground_floor'     comma separated list of valid keywords 

    # valid keywords and keywords_exclude vary depending on the country
    # the list of valid keywords can be requested using the keywords method (see below)
    # keywords should always be submitted as shown here; 
    # lowercased and with _ in place of space

DE ES IT UK
altbau balkon barrierefrei baugrundstueck bungalow carport dachboden denkmalschutz doppelgarage ebk fahrstuhl fussbodenheizung garage garten gartennutzung kamin keller klimatisiert moebliert neubauten parkmoeglichkeit sauna solar swimmingpool tennisplatz terrasse tiefgarage unmoebliert versteigerung wg zentralheizung zwangsvollstreckung adosado amueblado atico balcon buhardilla bungalow calefac_central chimenea doble_garaje ex_vpo garaje garaje_particular gimnasio invernadero jacuzzi jardin jardin_comunitario lavavajillas loft obra_nueva piscina piscina_comunitaria piscina_individual pista_de_deportes planta_baja playa_cercana plaza_de_aparcamiento portero portero_automatico renovado sauna semi_amueblado sin_ambueblar sin_ascensor sotano suelo_de_madera terraza trastero villa arredato ascensore balcone caminetto cantina ex_casa_comunale garage giardino loft non_ammobiliato nuova_costruzionezione rudere terrazzo attic auction balcony basement bungalow cellar conservatory conversion cottage detached detached_garage dishwasher double_garage excouncil fireplace freehold furnished garage garden grade_ii gym high_ceilings hot_tub leasehold lift loft lower_ground_floor maisonette mews new_build off_street_parking parking patio penthouse porter purpose_built refurbished sauna sealed_bid semi_detached share_freehold shared_garden swimming_pool terrace unfurnished victorian wood_floor

Keywords:
This is a simple API method that returns a sorted list of valid keywords.

An example request would be (white space inserted for clarity):

    http://api.nestoria.co.uk/api
      ? action   = keywords
      & encoding = xml
  

Metadata: new!
By using the metadata method you can request aggregated information about an area live average house prices.

An example request would be (white space inserted for clarity):

    http://api.nestoria.co.uk/api
      ? action     = metadata
      & encoding   = xml
      & place_name = soho
  
which gives back responses with average house, flat and property prices with data aggregated monthly and quarterly. We also show how many datapoints the data is based on (see the example response below).

JSON callbacks:
The callback parameter (callback=function) wraps the JSON output text in parentheses and a function name of your choosing.

Callback function names may only use upper and lowercase alphabetic characters (A-Z, a-z), numbers (0-9), the period (.), the underscore (_), and brackets ([ and ]). Brackets must be URL-encoded.

There is a great discussion of JSON callbacks on the Yahoo! Developer Network. We've intentionally modeled our API to be the same as those cool kids over at Yahoo! As you can read on their site Callbacks are particularly useful for use with web service requests in client-side JavaScript...

Some examples:

UK: So for example to search for a flat to rent near the Nestoria offices in London, UK you would use this URL:

    http://api.nestoria.co.uk/api
        ? action       = search_listings
        & encoding     = json
        & place_name   = soho
        & listing_type = rent
        & pretty       = 1

The response to this request will look something like this:

    {
      "request" : {
        "action" : "search_listings",
        "country" : "uk",
        "encoding" : "json",
        "language" : "en",
        "listing_type" : "rent",
        "number_of_results" : 20,
        "place_name" : "soho",
        "sort" : "nestoria_rank",
        "version" : 1.14
      },
      "response" : {
        "attribution" : {
            "img_url" : "http://static.nestoria.co.uk/i/realestate/uk/en/pb.png",
            "img_height" : 20,
            "img_width" : 200,
            "link_to_img" : "http://www.nestoria.co.uk",
        }
        "created_http" : "Thu, 06 Jul 2006 12:31:57 GMT",
        "created_unix" : 1152189117,
        "link_to_url" : "http://www.nestoria.co.uk/soho/property/rent",
        "listings" : [
          {
            "bathroom_number" : 2,
            "bedroom_number" : 2,
            "datasource_name" : "Winkworth",
            "keywords" : "Balcony, Garden, High Ceilings, Unfurnished",
            "latitude" : 51.5111,
            "lister_name" : "Winkworth",
            "lister_url" : "http://rd.nestoria.co.uk/rd?url=1-U2FsdGVkX1_yif8.....",
            "listing_type" : "rent",
            "longitude" : -0.127266,
            "price" : 600,
            "price_currency" : "GBP",
            "price_formatted" : "£600 per week",
            "price_type" : "per week",
            "property_type" : "flat",
            "summary" : "Cool, Sleek and Hip! Perfect for any web service developer...",
            "thumb_height" : 60,
            "thumb_url" : "http://limg.nestoria.co.uk/a/3/a3f6be29d2902b013d1582dc140c976c.jpg",
            "thumb_width" : 60,
            "title" : "Garrick Street, Covent Garden, WC2",
            "updated_in_days" : 6.5
          },
          // removed listings to keep it short.
        ],
        "locations" : [
          {
            "place_name" : "soho_(wc2)",
            "title" : "Soho",
            "long_title" : "Soho,
          }
        ]
        "sort" : "nestoria_rank"
        "status_code" : 200,
        "status_text" : "OK",
        "thanks" : "For using the Nestoria API."
      }
    }

Spain: perhaps you're looking for a place to rent in Palma de Mallorca. No problem, just use a URL like this

    http://api.nestoria.es/api
        ? action       = search_listings
        & encoding     = json
        & place_name   = palma%20de%20mallorca
        & listing_type = rent
        & pretty       = 1

The response to this request will look something like this:

{
  "request" : {
    "action" : "search_listings",
    "country" : "es",
    "encoding" : "json",
    "language" : "es",
    "listing_type" : "rent",
    "number_of_results" : 20,
    "place_name" : "palma de mallorca",
    "pretty" : 1,
    "sort" : "nestoria_rank"
    "version" : 1.14
  },
  "response" : {
    "attribution" : {
        "img_url" : "http://static.nestoria.es/i/realestate/es/es/pb2.png",  
        "img_height" : 20,
        "img_width" : 199,
        "link_to_img" : "http://www.nestoria.es",
    }
    "created_http" : "Mon, 07 May 2007 12:00:44 GMT",
    "created_unix" : 1178539244,
    "link_to_url" : "http://www.nestoria.es/palma-de-mallorca/casa/alquiler/num_res-20",
    "listings" : [
      {
        "bathroom_number" : 2,
        "bedroom_number" : 2,
        "datasource_name" : "Atrea",
        "keywords" : "Furnished, Attic",
        "latitude" : 39.5366,
        "lister_name" : "Alfa",
        "lister_url" : "http://rd.nestoria.es/rd?l=api-sr-title-1&sc=1-13946&url=1-U2FsdGVk....",
        "listing_type" : "let",
        "longitude" : 2.71594,
        "price" : 750,
        "price_currency" : "EUR",
        "price_formatted" : "750 EUR per month",
        "price_type" : "monthly",
        "property_type" : "flat",
        "sort" : null,
        "summary" : "Bonito atico en las maravillas nuevo a estrenar, vistas al mar y...",
        "thumb_height" : 60,
        "thumb_url" : "http://limg.nestoria.es/c/3/c32295a2a0251437bd9981a0633158aa.jpg",
        "thumb_width" : 60,
        "title" : "Piso de 2 habitaciones en alquiler",
        "updated_in_days" : 0.5
      },
      "sort" : "nestoria_rank"
      "status_code" : 200,
      "status_text" : "OK"
      "thanks" : "For using the Nestoria API."
    }
}

The interesting part of these responses are the 'listings'. This is an array of hashes, each hash describing an individual listing. Hopefully the fields are all self explanatory.

Please note that the returned lister_urls are encrypted. Please don't change them (for example lowercasing), as the URL will no longer work. Thanks.

We currently cap the number of listings per query at 50, mainly to make things easy for our database. We think 50 should be enough for almost all applications. If you need more please get in touch and we'll look at your case individually.

There is also an array of locations. If there is a single entry then that is the location that was used to find the properties in 'listings'.

Sometimes it is not possible to uniquely identify a 'place_name'. For example if you searched for a place_name like 'alford' then the system cannot work out which location to use, and you will receive a list of alternatives and no listings:

    
      "locations" : [
         {
            "long_title" : "Alford",
            "place_name" : "alford_gu6",
            "title" : "Alford"
         },
         {
            "long_title" : "Alford, Aberdeenshire",
            "place_name" : "alford_ab",
            "title" : "Alford"
         },
         {
            "long_title" : "Alford, Lincolnshire",
            "place_name" : "alford_ln",
            "title" : "Alford"
         },
         {
            "long_title" : "Alford, Somerset",
            "place_name" : "alford_castlecary",
            "title" : "Alford"
         }
      ],

In this case you should select one of the locations and use the given 'place_name' to do another search.

metadata requests have their own response format, but hopefully one that can quickly be deciphered. Here's a JSON formatted example:
        {
            "data" : {
               "2007_m9" : {
                  "avg_price" : "503112.07",
                  "datapoints" : "15"
               }
            },
            "currency"      : "GBP",
            "num_beds"      : "1",
            "property_type" : "flat",
            "price_type"    : "fixed",
            "listing_type"  : "buy",
            "url"           : "http://www.nestoria.co.uk/chelsea/flat/buy/bedrooms-1/maxbed-1",
            "metadata_name" : "avg_1bed_flat_buy_monthly",
         },
  

i.e. the monthly data for the average price of buying a one bed flat, in month 9 (September) of 2007 - £503,111.07 based on 15 data points. Each metadata response includes a metadata_name field in its body. This essentially illustrates all the relevant meta-information associated with the data returned.

The string is composed by several parts which can be broken down to:

  • number_of_beds
  • property_type
  • listing_type
  • interval
The interval can either be monthly or quarterly.
For example: avg_1bed_flat_buy_monthly denotes the average buying price for a one bedroom flat derived from datapoints aggregated over the period of one month.

That is it - please feel free to contact us if there is anything that is unclear or if you have any feature requests.

Thanks:
Many thanks to all the developers out there who submitted error reports, supplied feedback, wrote libraries, and have generally been amazingly supportive.
Last Updated
This document was last updated on 8th September, 2008

Change Log:
The current API version is '1.14'