Gaze - the mySociety Gazetteer web service

Overview

There is general information about Gaze in the blog post which announced its launch, and another blog post about population density.

Language specific APIs

Use the REST based API as described below.

Perl users can use WWW::MySociety::Gaze, which wraps the REST API.

Usage instructions

When calling http://gaze.mysociety.org/gaze-rest parameter f is always the function name, with the following parameters. The content of the page returned is whitespace seperated, except where otherwise specified.

get_country_from_ip

Return the ISO country code for the given IP address, or undef if none could be found.

get_coords_from_ip

Return latitude and longitude of the centre of the country for the given IP address, or undef if none could be found.

get_find_places_countries

This function takes no parameters and returns list of countries which find_places will work for (one item per line).

find_places

Returns a CSV file of places in COUNTRY (ISO code) which match the given search QUERY. The country must be from the list returned by get_find_places_countries. STATE, if specified, is a customary code for a top-level administrative subregion within the given COUNTRY; at present, this is only useful for the United States.

Returns a set of lines, in the format

                NAME, IN, NEAR, LATITUDE, LONGITUDE, STATE, SCORE
When IN is defined, it gives the name of a region in which the place lies; when NEAR is defined, it gives a short list of other places near to the returned place. These allow nonunique names to be disambiguated by the user. LATITUDE and LONGITUDE are in decimal degrees, north- and east-positive, in WGS84. Earlier entries in the returned list are better matches to the query. At most MAXRESULTS (default, 20) results, and only results with score at least MINSCORE (default 0, per- centage from 0 to 100) are returned. The MAXRESULTS limit is ignored when the top results all have the same relevancy. They are all returned. So for example, this means that if you search for Cambridge in the US with MAXRESULTS of 5, it will return all the Cambridges, even though there are more than 5 of them.

get_country_bounding_coords

Returns a space sperated line containing the latitude of the most northerly and southernly places, and the lon- gitude of the most easterly and westerly places in COUNTRY. (NB these will always lie *inside* the true bounding coordinates of the COUNTRY itself.)

get_population_density

Returns an estimate of the population density at (LAT, LON) in persons per square kilometer.

get_radius_containing_population

Return an estimate of the radius (in km) of the smallest circle around (LAT, LON) which contains at least NUMBER people. If MAXIMUM is defined, return that value rather than any larger computed radius; if not specified, use 150km.

get_places_near

Population or Distance must be specified

Returns a CSV formatted page of all the places within a given distance of a point expressed as LAT LON. PARAMS include: * DISTANCE to include all results within DISTANCE km * POPULATION to include all results within a circle containing at least POPULATION people * MAXDISTANCE, can be supplied with POPULATION to bound the distance returned * COUNTRY to bound results to one COUNTRY