WebService::Nestoria::Search - Perl interface to the Nestoria Search public API.
version 1.021004
WebService::Nestoria::Search provides a Perl interface to the public API of Nestoria, a vertical search engine for property listings.
WebService::Nestoria::Search is currently written to be used with v1.18 of the Nestoria API.
Functions and documentation are split over WebService::Nestoria::Search, WebService::Nestoria::Search::Request, WebService::Nestoria::Search::Response and WeebService::Nestoria::Search::Result. However you need only ever use WebService::Nestoria::Search, and the others will be used as necessary.
A Request object stores the parameters of the request, a Response object stores the data retrieved from the API (in JSON and Perl hashref formats), and a Result represents an individual listing.
The possible parameters and their defaults are as follows:
country (default: 'uk') warnings (default: 1) action (default: 'search_listings') version encoding (default: 'json') pretty (default: 0) number_of_results page place_name south_west north_east centre_point radius listing_type property_type price_max price_min bedroom_max bedroom_min bathroom_max bathroom_min room_max room_min size_max size_min sort keywords keywords_exclude
If parameters are passed to new they are used as the defaults for all calls to the API. Otherwise they can be passed to the querying functions (eg. query) as per-search parameters.
new
query
You should never have to set the 'action' parameter yourself, it is implied by the method you choose to use to run the query.
use WebService::Nestoria::Search; my $NS = WebService::Nestoria::Search->new( place_name => 'soho', listing_type => 'rent', property_type => 'flat', price_max => '500', number_of_results => '10', ); my @results = $NS->results( keywords => 'garden,hot_tub,mews', keywords_exclude => 'cottage,wood_floor' ); foreach my $result (@results) { print $result->get_title, "\n"; }
@listings is an array of WebService::Nestoria::Search::Result objects.
@listings
my $request = $NS->request; print "Will fetch: ", $request->url, "\n"; my $response = $request->fetch;
my $response = $NS->query; if ($response->status_code == 200) { print "Success! Got ", $response->count, " results\n"; } print "Raw JSON\n", $response->get_json, "\n"; while (my $result = $response->next_result) { print $result->get_thumb_url, "\n"; }
my @bound_results = $ns->results('south_west' => '51.473685,-0.148315', 'north_east' => '50.473685,-0.248315'); foreach my $result (@bound_results) { print $result->get_title, "\n"; }
Creates a WebService::Nestoria::Search object. On error sets $@ and returns undef.
$@
undef
If given 'request' parameters (eg. place_name, listing_type) these become defaults for all calls to the API.
my %args = (warnings => 0, listing_type => 'rent', place_name => 'soho'); my $NS = WebService::Nestoria::Search->new(%args);
Creates a WebService::Nestoria::Search::Request object. On error sets $@ and returns undef
my $request = WebService::Nestoria::Search->request(%args);
Queries the API and returns a WebService::Nestoria::Search::Response object. On error, sets $@ and returns undef.
my $response = $NS->query(%args);
This is a shortcut for
my $request = $NS->request(%args); my $response = $request->fetch;
Returns an array of WebService::Nestoria::Search::Result objects. On error, sets $@ and returns undef.
my @results = $NS->results(%args);
my $request = $NS->request(%args); my $response = $request->fetch; my @results = $response->results;
Uses the API feature 'action=echo' to test the connection.
Returns 1 if the connection is successful and 0 otherwise.
unless ($NS->test_connection) { die "Cannot establish connection with Nestoria API\n"; }
Uses the API feature 'action=keywords' to return a list of valid keywords. A current list of keywords can be found at the below URL, but do not hardcode the list of keywords in your code as it is occasionally subject to change.
my @keywords = $NS->keywords;
Taken from http://www.nestoria.co.uk/help/api-tech.
Uses the API feature 'action=metadata' to return metadata about the listings. Returns a WebService::Nestoria::Search::MetadataResponse object with average house, flat and property prices aggregated monthly and quarterly.
my $metadata_response = WebService::Nestoria::Search->metadata(%args);
Returns a URI object representing the URL that was last fetched by WebService::Nestoria::Search::Request.
Returns the URL that was last fetched by WebService::Nestoria::Search::Request.
Warnings is true by default, and means that errors are output to STDERR as well as being returned via $@. This can be turned off either on the use line
use
use WebService::Nestoria::Search Warnings => 0;
or when calling new
my $NS = WebService::Nestoria::Search->new(Warnings => 0);
Country is an optional parameter which defaults to 'uk'. It affects the URL which is used for fetching results.
Currently the available countries are:
uk - United Kingdom
es - Spain
it - Italy
de - Germany
fr - France
br - Brazil
in - India
It is possible to run WebService::Nestoria::Search functions without creating an object. However, no functions are exported (by default or otherwise) so the full name must be used.
my @results = WebService::Nestoria::Search->results(%args);
Copyright (C) 2009 Lokku Ltd.
Alex Balhatchet (alex@lokku.com)
Patches supplied by Yoav Felberbaum and Alistair Francis.
A lot of the ideas (and yes, very occasionally entire functions) for these modules were borrowed from Jeffrey Friedl's Yahoo::Search.
This module would not exist without the public API available from Nestoria (http://www.nestoria.co.uk/help/api.)
To install WebService::Nestoria::Search, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Nestoria::Search
CPAN shell
perl -MCPAN -e shell install WebService::Nestoria::Search
For more information on module installation, please visit the detailed CPAN module installation guide.