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

Copyright (c) 2008, Andy Armstrong <andy@hexten.net>.

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