Alex Balhatchet > WebService-Nestoria-Search > WebService::Nestoria::Search

Download:
WebService-Nestoria-Search-1.022002.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.022002   Source  

NAME ^

WebService::Nestoria::Search - Perl interface to the Nestoria Search public API.

VERSION ^

version 1.022002

SYNOPSIS ^

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.22 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.

Parameters

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.

You should never have to set the 'action' parameter yourself, it is implied by the method you choose to use to run the query.

Simple Example

    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.

Using the Request object

    my $request = $NS->request;

    print "Will fetch: ", $request->url, "\n";

    my $response = $request->fetch;

Using the Response object

    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";
    }

Using a bounding box

    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";
    }

FUNCTIONS ^

new

Creates a WebService::Nestoria::Search object. On error sets $@ and returns 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);

request

Creates a WebService::Nestoria::Search::Request object. On error sets $@ and returns undef

    my $request = WebService::Nestoria::Search->request(%args);

query

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;

results

Returns an array of WebService::Nestoria::Search::Result objects. On error, sets $@ and returns undef.

    my @results = $NS->results(%args);

This is a shortcut for

    my $request = $NS->request(%args);
    my $response = $request->fetch;
    my @results = $response->results;

test_connection

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";
    }

keywords

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.

metadata

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);

last_request_uri

Returns a URI object representing the URL that was last fetched by WebService::Nestoria::Search::Request.

last_request_url

Returns the URL that was last fetched by WebService::Nestoria::Search::Request.

Warnings ^

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 WebService::Nestoria::Search Warnings => 0;

or when calling new

    my $NS = WebService::Nestoria::Search->new(Warnings => 0);

Country ^

Country is an optional parameter which defaults to 'uk'. It affects the URL which is used for fetching results.

Currently the available countries are:

Australia (au) supports the metadata requests but not listings requests

Non-OO ^

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 ^

Copyright (C) 2014 Lokku Ltd.

Author ^

Alex Balhatchet (alex@lokku.com)

Patches supplied by Yoav Felberbaum, Alistair Francis, Ed Freyfogle

Acknowledgements ^

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.)

syntax highlighting: