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'