NAME

WWW::MySociety::Gaze - An interface to MySociety.org's Gazetteer service

VERSION

This document describes WWW::MySociety::Gaze version 0.02

SYNOPSIS

    use WWW::MySociety::Gaze;

DESCRIPTION

MySociety.org Gaze is a REST based gazetteer service. You can find out more about it here:

http://www.mysociety.org/2005/09/15/gaze-web-service/

WWW::MySociety::Gaze is a Perl wrapper around Gaze.

INTERFACE

`new`

Create a new WWW::MySociety::Gaze.

`get_country_from_ip( $ip )`

Guess the country of location of a host from its dotted quad IP address. Returns an ISO country code or undef if the country code is unknown.

    my $gaze = WWW::MySociety::Gaze->new;
    my $country = $gaze->get_country_from_ip( '82.152.157.85' );

`get_find_places_countries`

Return the list of countries for which find_places has a gazetteer available.

Takes no arguments, returns a list of ISO country codes.

    my $gaze = WWW::MySociety::Gaze->new;
    my @countries = $gaze->get_find_places_countries;

`find_places`

Lookup a location in the gazetteer. Takes a number of key, value pairs as follows:

Parameters

country: ISO country code of country in which to search for places
state: State in which to search for places; presently this is only meaningful for country=US (United States), in which case it should be a conventional two-letter state code (AZ, CA, NY etc.); optional
query: Query term input by the user; must be at least two characters long
maxresults: Largest number of results to return, from 1 to 100 inclusive; optional; default 10
minscore: Minimum match score of returned results, from 1 to 100 inclusive; optional; default 0

Returns a list of hash references. Each hash has the following fields:

Name: Name of the place described by this row
In: Blank, or the name of an administrative region in which this place lies (for instance, a county)
Near: A reference to a (possibly empty) array of nearby placenames.
Latitude: WGS-84 latitude of place in decimal degrees, north-positive
Longitude: WGS-84 longitude of place in decimal degrees, east-positive
State: Blank, or containing state code for US
Score: Match score for this place, from 0 to 100 inclusive

`get_population_density( $lat, $lon )`

Given a latitude, longitude pair return an estimate of the population density at (lat, lon), in persons per square kilometer.

`get_radius_containing_population`

Return an estimate of the smallest radius around (lat, lon) containing at least number persons, or maximum, if that value is smaller. Takes key value parameters:

lat: WGS84 latitude, in decimal degrees
lon: WGS84 longitude, in decimal degrees
number: number of persons
maximum: largest radius returned, in kilometers; optional; default 150

`get_country_bounding_coords`

Get the bounding box of a country given its ISO country code. Returns a four element list containing max_lat, min_lat, max_lon, min_lon.

    my @bb = $gaze->get_country_bounding_coords( 'GB' );

`get_places_near`

Get a list of places near a specific location. Takes a list of name, value pairs like this:

lat: WGS84 latitude, in north-positive decimal degrees
lon: WGS84 longitude, in east-positive decimal degrees
distance: distance in kilometres
number: number of persons to calculate circle radius
maximum: maximum radius to return (default 150km)
country: ISO country code of country to limit results to (optional)

Returns a list of hash references like this:

Name: Name of the nearby place.
Distance: Distance from the base place.
Latitude: Latitude of the nearby place.
Longitude: Longitude of the nearby place.
Country: Country of the nearby place.
State: State of the nearby place (currently US only).

CONFIGURATION AND ENVIRONMENT

WWW::MySociety::Gaze requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-www-mysociety-gaze@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Andy Armstrong <andy@hexten.net>

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.