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

  • "ip" is the IP address to lookup

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

get_coords_from_ip

  • "ip" is the IP address to lookup

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

  • "country" is the ISO country code to search for places
  • "state" is the optional state within a country to search in.
  • "query" is the name being looked for.
  • "maxresults" is the maximum results to return (optional)
  • "minscore" is the smallest percentage score for results.

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

  • "country" is the ISO country code to return co-ordinates for

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

  • "lat" is the latitude, north-positive in decimal degrees
  • "lon" is the longtitude, east-positive in decimal degrees

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

get_radius_containing_population

  • "lat" is the latitude, north-positive in decimal degrees
  • "lon" is the longtitude, east-positive in decimal degrees
  • "number" is the population
  • "maximum" is the maximum radius to return (default 150, optional)

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

  • "lat" is the latitude, north-positive in decimal degrees
  • "lon" is the longtitude, east-positive in decimal degrees
  • "population" is the number of persons to calculate circle radius (optional)
  • "distance" is the maximum distance population (optional)
  • "country" is the ISO country code to limit results to (optional)

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