GeoNames API and Services Documentation

Syntax: $result = geonames_query($service, $query, $options)

Parameter: $service (string)

The "Usage Instructions for Installed Services" below, lists all the currently installed services available on your system. Please look there for details on the various services.

Parameter: $query (associative array)

Queries (query parameters) are defined as associative arrays, as the one above. For a list of allowed query parameters, please see the specific service under "Usage Instructions for Installed Services".

Example: $query = array('lat' => 59.95, 'lng' => 10.77)

This query can be used with all services that require the parameters lat and lng, for example Find Nearby Place Name.

The query parameters are usually integers (numbers) or strings (text), but for a few services they are allowed to be arrays (multiple values) in order to be able to pass several values of the same type (for instance countries or featurecodes), in the example below we pass on two countries.

Example: $query = array('name' => 'Holmen', 'country' => array('NO','SE'))

If you use this query with the 'search' service (GeoNames Fulltext Search), you will find places with the name Holmen in Norway or Sweden

Parameter: $options (associative array) - optional

You may use the $option parameter to modify the results. Limit the number of fields returned, order the columns, or sort the rows. The options array has three optional properties: columns, sortby and sortorder (all of them may be used independently).

columns is an array of fieldnames

Example: $options = array('columns' => array('countryname', 'countrycode') )

By passing this option your results will only contain the two columns specified (countryname and countrycode). The result object will also be arranged with your results in the specified order.

sortby is a fieldname (string)

Example: $options = array('sortby' => 'countryname')

By passing this option your results will be ordered by the countryname.

sortorder is either ASC or DESC (string)

Example: $options = array('sortorder' => 'DESC')

By passing this option your results will be returned in a descending order (Your list of Countries would start with the letter Z).

Multiple Options Example: $options = array('sortby' => 'countryname', 'sortorder' => 'DESC')

This option would return your results ordered by Country Name, descending.

Result: $result (object)

The results object will look something like this:

$result->results = array(
  [0] = array('name' => 'Oslo', ...)                   
  [1] = array('name' => 'Nydalen', ...)
  ...
) 
$result->total_results_count = integer, number of total results
$result->service = string service name
$result->request = array (
  'url' = URL sent to GeoNames server
  'bytes' = size of data requested from GeoNames server  
  'seconds' = time used for request to GeoNames server
  'cached' = if the result is loaded from the cache, this variable is set to the cache type (result or data)
) 
$result->query = array(
  'lat' = 23
  'lng' = 34
  'maxrows' = 10
  ...
)
$result->pager = array() - associative array, only available for some services
$result->standalone = if set to no, the GeoNames commercial service is used

In the usage instructions below, bold parameters are mandatory. Parameters that are structured like 'key=value' are default values for parameters, and may be overridden. Items in italics are optional parameters. Services with multiple bold parameters may be one out of two types; single or all - read the instructions carefully.

Usage Instructions for Installed Services

Place Hierarchy: Children

Purpose: Find the children of a given geonameId.

Usage: $result = geonames_query('children', $query, $options)

$query = array(geonameid, style, lang)

$result->results = array(name, lat, lng, geonameid, countrycode, countryname, fcl, fcode, distance, fcodename, fclname, population, elevation, alternatenames, admincode1, admincode2, adminname1, adminname2, timezone, dstoffset, gmtoffset) -- FULL style

Country Code (reverse geocoding)

Purpose: Find Country Code from latitude and longitude

Usage: $result = geonames_query('countrycode', $query, $options)

$query = array(lat, lng, lang)

both bold parameters are required

$result->results = array(countrycode, countryname)

Country Info (Bounding Box, Capital, Area in square km, Population)

Purpose: Find countries for which postal code geocoding is available.

Usage: $result = geonames_query('countryinfo', $query, $options)

$query = array(country, lang)

$result->results = array(countrycode, countryname, isonumeric, isoalpha3, fipscode, continent, capital, areainsqkm, population, currencycode, languages, geonameid, bboxwest, bboxnorth, bboxsouth, bboxeast)

Country Subdivision (reverse geocoding)

Purpose: Find Country Code from latitude and longitude

Usage: $result = geonames_query('countrysubdivision', $query, $options)

$query = array(lat, lng, lang)

both bold parameters are required

$result->results = array(countrycode, countryname, admincode1, adminname1)

Place Hierarchy: Hierarchy

Purpose: Find all Geonames higher up in the hierarchy of a place name.

Usage: $result = geonames_query('hierarchy', $query, $options)

$query = array(geonameid, style, lang)

Find nearby Place Name (reverse geocoding)

Purpose: Find nearby place name (reverse geocoding)

Usage: $result = geonames_query('nearbyplace', $query, $options)

$query = array(lat, lng, radius=20, radius, maxrows, style)

both bold parameters are required

Find nearby Postal Codes (reverse geocoding)

Purpose: Find nearby Postal Codes (reverse geocoding)

Usage: $result = geonames_query('nearbypostalcodes', $query, $options)

$query = array(lat, lng, maxrows=15, radius=10, style=medium, radius, postalcode, maxrows, country, style)

both bold parameters are required

$query = array(postalcode, country, maxrows=15, radius=10, style=medium, lat, lng, radius, maxrows, style)

both bold parameters are required

$result->results = array(postalcode, name, countrycode, lat, lng, distance, admincode1, admincode2, admincode3, adminname1, adminname2, adminname3)

Find nearby Wikipedia Entries (reverse geocoding)

Purpose: Find nearby Wikipedia Entries (reverse geocoding)

Usage: $result = geonames_query('nearbywikipedia', $query, $options)

$query = array(lat, lng, maxrows=15, radius=10, radius, postalcode, lang, maxrows, country)

both bold parameters are required

$query = array(postalcode, country, maxrows=15, radius=10, lat, lng, radius, lang, maxrows)

both bold parameters are required

$result->results = array(summary, feature, population, elevation, lat, lng, wikipediaUrl, thumbnailImg, lang, distance)

Place Hierarchy: Neighbours

Purpose: Returns the neighbours for a given geonameId.

Usage: $result = geonames_query('neighbours', $query, $options)

$query = array(geonameid, style, lang)

Postal Code Country Info

Purpose: Find countries for which postal code geocoding is available.

Usage: $result = geonames_query('postalcodecountryinfo', $query, $options)

$query = array()

$result->results = array(countrycode, countryname, numpostalcodes, minpostalcode, maxpostalcode)

Postal Code Search

Purpose: Postalcode search provides placenames/postalcodes for locations.

Usage: $result = geonames_query('postalcodesearch', $query, $options)

$query = array(postalcode, placename, maxrows=10, style=medium, maxrows, style, country)

just one of the bold parameters is required

$result->results = array(postalcode, name, countrycode, lat, lng, admincode1, adminname1, admincode2, adminname2, admincode3, adminname3)

GeoNames Fulltext Search

Purpose: Search provides names and information for geographical locations, it is probably the most comprehensive search available from GeoNames and has numereous possible parameter combinations. Note that this service allows some parameters to be arrays: country, featureclass and featurecode.

Usage: $result = geonames_query('search', $query, $options)

$query = array(query, name, name_equals, maxrows=15, featureclass=p, startrow=0, maxrows, startrow, country, admincode1, admincode2, admincode3, featureclass, featurecode, lang, style)

country is allowed to be an array of strings
featurecode is allowed to be an array of strings
featureclass is allowed to be an array of strings
just one of the bold parameters is required

Place Hierarchy: Siblings

Purpose: Returns the siblings for a given geonameId.

Usage: $result = geonames_query('siblings', $query, $options)

$query = array(geonameid, style, lang)

Timezone

Purpose: Find the timezone for a given lat/lng with gmt offset (1. January) and dst offset (1. July)

Usage: $result = geonames_query('timezone', $query, $options)

$query = array(lat, lng)

both bold parameters are required

$result->results = array(countrycode, countryname, lat, lng, timezoneid, dstoffset, gmtoffset)

Wikipedia Articles from Bounding Box

Purpose: Search Wikipedia entries within the Bounding Box

Usage: $result = geonames_query('wikipediabbox', $query, $options)

$query = array(north, south, east, west, maxrows=15, lang, maxrows)

all bold parameters are required

$result->results = array(lang, title, summary, feature, population, elevation, lat, lng, wikipediaurl, thumbnailimg)

Wikipedia Fulltext Search

Purpose: Search Wikipedia entries in Fulltext

Usage: $result = geonames_query('wikipediasearch', $query, $options)

$query = array(query, maxrows=15, title, lang, maxrows)

$query = array(title, maxrows=15, query, lang, maxrows)

$result->results = array(lang, title, summary, feature, population, elevation, lat, lng, wikipediaurl, thumbnailimg)

GeoNames API for Drupal - the whole world in one function

New forum topics

GeoNames API and Services Documentation

Usage Instructions for Installed Services

Active Forum Topics

Recent Comments