NAME

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

VERSION

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

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

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.