Home > Nestoria API - Methods - Search Listings

search_listings returns listing records from the Nestoria database. The same sorting and filtering are used as are used on the main Nestoria website. Unfortunately, not all of our partners wants their listings to be found via our API, so the listing returns may not match precisely with those available on our sites. It's complicated and we're working on it.

We offer the search_listings method for all Nestoria countries EXCEPT Australia.

There are some limitations, for example we return OK if either listings or the location was found. This means that you have to check for listings in the returned data and cannot rely on the OK.

Another limitation is that queries against very large areas, e.g. the whole country, are slow. We (silently) reduce the size of the requested area to reduce the load on our databases. Of course, you will still get a lot of listings results back.

Please read the notes on the various parts of the returned data on this page.

Request

These are the location arguments which you can pass:

parameter description
place_name anything you would type into the search box on Nestoria: a place name, post code, tube station, etc.
e.g. "Chelsea" or "SW14"
south_west
north_east
a bounding box in the format latitude,longitude,latitude2,longitude2
e.g. &south_west=51.684183,-3.431481&north_east=51.85415,-3.077859
centre_point latitude and longitude. A default radius of 2km will be used.
e.g. &centre_point=51.684183,-3.431481
radius latitude, longitude and a radius in either kilometres (km) or miles (mi). Note that the 'km' or 'mi' has to be set. e.g. &centre_point=51.684183,-3.431481,10km

To search for specific listings based on id:

Each listing we return has a unique "GUID". To check if a certain listing exists you can search by GUID, and in this case you should NOT set the location, filters, sorting or pagination options. The results returned in the response will only contain the listings information for the specified GUIDs.

parameter description
guid A unique identifier for a single property. To retrieve several properties, separate GUIDs by commas. Note that unlike with most other parameters you need to take care of proper upper/lowercasing.
e.g. &guid=guid-g1-TNtcDN0ATMwkAM==,guid-g1-TNtczM2IDO5YwN==

These are the arguments for specifying filters which you can pass:

parameter description
listing_type Either 'buy' (default), 'rent' or 'share'
price_min
price_max
Numbers. Instead of setting '0' and '999999999' you can use 'min' and 'max'
e.g. &price_min=min&price_max=200000
bedroom_min
bedroom_max
Numbers. 0 stands for 'studio apartment'. Instead of setting '0' and '999999999' you can use 'min' and 'max'. Note: In the UK and Spain it's conventional to search by number of bedrooms, whereas in other countries it's conventional to search by total number of rooms.
e.g. &bedroom_min=3&bedroom_max=3
room_min
room_max
Numbers. Instead of setting '0' and '999999999' you can use 'min' and 'max'. Note: In the UK and Spain it's conventional to search by number or bedrooms, whereas in other countries it's conventional to search by total number of rooms.
e.g. &room_min=3&room_max=3
bathroom_min
bathroom_max
Numbers. Instead of setting '0' and '999999999' you can use 'min' and 'max'.
size_min
size_max
size_type
Numbers. Instead of setting '0' and '999999999' you can use 'min' and 'max'. size_type is either 'net' (default for Germany) or 'gross' (default for all others). Note: We don't support this parameter for the UK.
keywords
keywords_exclude
A comma separated list of keywords. You can set the positive filter, negative filter or both.
See the lists of valid keywords for details of what can be used. These vary by country (i.e. by which server the query is sent to); see the lists for full details.
e.g. &keywords=garden&keywords_exclude=terrace,carport
has_photo Set to 1 to retrieve only listings that have a photo.
updated_min A UNIX timestamp (UTC)
e.g. &updated_min=1220155200

These are the arguments for specifying sorting and pagination which you can pass:

You can only retrieve the first 1,000 results from the API. If you request 20 results per page that's 50 pages, whereas if you request 50 results per page that's only 20 pages. We have found that on Nestoria users tend to stop after a couple of pages and then start to re-filter or re-sort the results.

parameter description
number_of_results Defaults to 20. The maximum is 50.
page Defaults to 1. For example if you set &page=2 then results 21-40 are returned. The result contains an attribute "total_pages".
sort Defaults to "relevancy" which is the same as the "Nestoria Rank" which we use on the main Nestoria search.
  • relevancy
  • bedroom_lowhigh
  • bedroom_highlow
  • price_lowhigh
  • price_highlow
  • newest
  • oldest
  • random
  • distance

Example results

country example
nestoria.com.br example request and return structure (opens in new window)
nestoria.de example request and return structure (opens in new window)
nestoria.es example request and return structure (opens in new window)
nestoria.fr example request and return structure (opens in new window)
nestoria.in example request and return structure (opens in new window)
nestoria.it example request and return structure (opens in new window)
nestoria.co.uk example request and return structure (opens in new window)

Locations

Place names are handled in the same way as on the main Nestoria search, for example spellchecking is enabled.

We always return a list (array) of matched locations. The listings will be from the first matched location; the others can be used for "did you mean?" suggestions for users.

In some cases it is not possible to uniquely identify a 'place_name'. For example, there are many villages called 'Albury' in the UK. In this case, we return a list of locations including the field 'place_name' which you can use to carry out another request.

            "locations" : [
                    {
                       "center_lat" : "51.209119",
                       "center_long" : "-0.489769",
                       "long_title" : "Albury, Guildford",
                       "place_name" : "albury_guildford",
                       "title" : "Albury"
                    },
                    {
                       "center_lat" : "51.739892",
                       "center_long" : "-1.052779",
                       "long_title" : "Albury, Thame",
                       "place_name" : "albury_thame",
                       "title" : "Albury"
                    },
                    {
                       "center_lat" : "51.904418",
                       "center_long" : "0.088967",
                       "long_title" : "Albury, Ware",
                       "place_name" : "albury_ware",
                       "title" : "Albury"
                    }
                 ],
        

Thumbnails

We return thumbnails in two sizes: 60x60 pixel and 160x120px. Every listing has the URLs set. If we don't have a thumbnail in our database we return a placeholder image. If you want to use your own placeholder image then you have to replace these URLs:

       

Location of listings

Not every listing will have a latitude and longitude. If they're omitted it can be because:

Listings which do have a latitude and longitude will also have a 'location_accuracy' field. This is an integer number between 1 and 10 denoting how accurate the longitude and latitude are, 1 being the worst and 10 being the best.

Estate agent

We return both a 'datasource_name' and a 'lister_name'. You need to display BOTH to the user since the 'lister_url' usually goes to the datasource (e.g. property portal) but the lister (e.g. estate agent) is the person that offers the property.

On Nestoria we display it as $datasource_name > $lister_name or sometimes $listername on $datasource_name. In rare cases datasource_name and lister_name are the same.