Nestoria API - Methods - Search Listings

search_listings method

search_listings returns listing records from the Nestoria database. The same data, sorting and filtering are used which are used on the main Nestoria website.

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 arguments which you can pass:

location

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

search for specific listings by 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==

filters

parameter	description
listing_type	Either 'buy' (default), 'rent' or 'share'
property_type	Either 'all' (default), 'house' or 'flat'
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

sorting and pagination

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

result

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:

• Our geocoding was not good enough and we were only able to match an approximate location; on Nestoria we don't show a map marker to users, so the API does not return a position as well
• Estate agents give us a location, but don't allow us to use it for the API

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.