GeoNames Web Service Documentation

GeoNames is mainly using REST webservices.

Important

Don't use the demo account in your own app or tests - it's only for the sample links on this page. Register your own free account instead.
The username parameter is required on every request.
URL-encode string parameters that contain spaces or special characters.
Prefer the JSON services from JavaScript - most browsers block cross-origin XML calls to another server.
See also: all webservices on one table, credits per request, and exceptions / error handling.

Postal code restrictions

Canada, Ireland and Malta: only the first letters of the full postal code (copyright reasons).
Argentina: the data file uses 4-digit codes, superseded by a new system in 1999.
Brazil: only major postal codes are available (codes ending in -000, one per municipality).

Elevation - ASTER Global Digital Elevation Model V2 (2011)

A product of METI and NASA. Sample area ca. 30m x 30m, covering latitudes between 83°N and 65°S.

Compared to SRTM3, ASTER GDEM has finer resolution but is unprocessed - it still contains occasional holes and data errors that SRTM3 has had corrected.

Url: http://api.geonames.org/astergdem?

Parameters

lat, lng - the coordinate to look up
request method: GET or POST

Result

A single number giving the elevation in meters. Ocean areas are masked as "no data" and returned as -32768.

Example

XML JSON

The plain-text variant also accepts lists of points via the lats/lngs parameters - up to 20 points per call on the free server, 2000 on the premium service.

CountryCode / reverse geocoding

The ISO country code for any given point.

Url: http://api.geonames.org/countryCode?

Parameters

lat, lng - the coordinate to look up
type - xml or JSON; without it, plain text is returned
lang - language for the country name (used with type=xml/JSON)
radius - buffer in km for the closest country in coastal areas (a positive value expands the area searched, negative reduces it)

Result

The ISO country code for the point. With type=xml or type=JSON the response also includes the full country name.

Example

XML JSON TXT

Country Info (bounding box, capital, area, population)

Url: http://api.geonames.org/countryInfo?

Parameters

country - ISO country code (optional, default is all countries)
lang - ISO-639-1 language code, e.g. en/de/fr/it/es (optional, default English)

Result

Capital, population, area in km², and the bounding box of the mainland (excluding offshore islands).

Example

XML JSON CSV

Country Subdivision / reverse geocoding

The ISO country code and administrative subdivision (state, province, ...) for any given point.

Url: http://api.geonames.org/countrySubdivision?

Parameters

lat, lng - the coordinate to look up
lang - default returns names in the local language
radius - buffer in km for the closest country in coastal areas
level - which ADM level to return

Result

The country and administrative subdivision for the point. Adding radius + maxRows instead returns the closest subdivisions ordered by distance.

Example

XML JSON

Extended Find Nearby Toponym / reverse geocoding

Returns the most detailed information available for a point - a combination of several other services depending on location: address details in the US, the place hierarchy elsewhere, or the ocean name over water.

Url: http://api.geonames.org/extendedFindNearby?

Parameters

lat, lng - the coordinate to look up

Result

The most detailed information available for the given point.

Example

XML

Find Nearby Toponym / reverse geocoding

Url: http://api.geonames.org/findNearby?

Parameters

lat, lng - the coordinate to look up
featureClass, featureCode - may be repeated; prefix a featureCode with '!=' to exclude it
radius - in km (optional)
maxRows - default 10
style - SHORT, MEDIUM, LONG, FULL (default MEDIUM)
localCountry - restrict the search to the local country in border areas (value=true)

Result

The closest toponym matching the given feature class/code for the point.

Example

XML JSON

Find Nearby Populated Place / reverse geocoding

Url: http://api.geonames.org/findNearbyPlaceName?

Parameters

lat, lng - the coordinate to look up
lang - language of the returned 'name' (the pseudo-language 'local' returns it in the local language)
radius - in km (optional)
maxRows - default 10
style - SHORT, MEDIUM, LONG, FULL (default MEDIUM)
localCountry - restrict the search to the local country in border areas
cities - optional filter: 'cities1000', 'cities5000' or 'cities15000'

Result

The closest populated place (feature class P) for the point; the distance element is in km.

Example

XML JSON

Find Nearby Postal Codes / reverse geocoding

Comes in two flavors: pass either a lat/lng, or a postalcode/placename.

Url: http://api.geonames.org/findNearbyPostalCodes?

Parameters

lat, lng, radius (km), maxRows (default 5), style, country (default all countries), localCountry, isReduced (only the first part of the code, for GB/NL)
or: postalcode, country, radius (km), maxRows (default 5)
Limits: 30km radius / 500 maxRows on the free service, 160km / 2500 maxRows on the premium service.

Result

Postal codes and places for the query, sorted by distance. For Canada the FSA (first 3 characters of the full code) is returned.

Example

XML JSON

Get GeoNames Feature for geonameId

Url: http://api.geonames.org/get?

Parameters

geonameId - required
lang - optional
style - optional

Result

The attributes of the GeoNames feature with the given geonameId.

Example

XML JSON

Elevation - GTOPO30

A global DEM with a horizontal grid spacing of 30 arc-seconds (roughly 1km), derived from several raster and vector topographic sources (USGS).

Url: http://api.geonames.org/gtopo30?

Parameters

lat, lng - the coordinate to look up (sample area ca. 1km x 1km)

Result

A single number giving the elevation in meters. Ocean areas are masked as "no data" and returned as -9999.

Example

XML JSON TXT

Neighbourhood / reverse geocoding

Neighbourhoods for US cities. Data provided by Zillow under a CC BY-SA license.

Url: http://api.geonames.org/neighbourhood?

Parameters

lat, lng - the coordinate to look up

Result

The neighbourhood for the given point.

Example

XML JSON

Ocean / reverse geocoding

The name of the ocean or sea at a given point.

Url: http://api.geonames.org/ocean?

Parameters

lat, lng - the coordinate to look up
radius - optional

Result

The ocean or sea for the given point.

Example

XML JSON

Postal Code Country Info

Url: http://api.geonames.org/postalCodeCountryInfo?

Result

The list of countries for which postal-code geocoding is available.

Example

XML JSON

Placename Lookup with Postal Code (JSON)

Url: http://api.geonames.org/postalCodeLookupJSON?

Parameters

postalcode
country
maxRows - default 20
callback
charset - default 'UTF-8'

Result

Places for the given postal code, sorted by postalcode then placename. JSON only.

Example

JSON

Postal Code Search

For the US, the first returned zip code is determined from zip-code area shapes; the remaining results (and all results for every other supported country) are based on centroids.

Url: http://api.geonames.org/postalCodeSearch?

Parameters

Parameter	Value	Description
postalcode	string (postalcode or placename required)	postal code
postalcode_startsWith	string	the first characters or letters of a postal code
placename	string (postalcode or placename required)	matched against placename, postal code, country, admin name (URL-encoded UTF-8)
placename_startsWith	string	the first characters of a place name
country	ISO-3166 country code (optional)	default is all countries; may be repeated, e.g. country=FR&country=GP
countryBias	string	records from this country are listed first
maxRows	integer (optional)	maximum rows returned; default 10
style	SHORT, MEDIUM, LONG, FULL (optional)	verbosity of the returned document; default MEDIUM
operator	AND, OR (optional)	AND requires every term in placename to match, OR any term; default AND
charset	string (optional)	encoding of the returned document; default 'UTF8'
isReduced	true or false (optional)	default 'false'; when true, only the UK outer code / NL 4 digits are returned
east, west, north, south	float (optional)	bounding box - only features inside it are returned

Result

A list of postal codes and places matching the placename/postalcode query.

Example

XML JSON

Elevation - SRTM1

Sample area ca. 30m x 30m.

Url: http://api.geonames.org/srtm1?

Parameters

lat, lng - the coordinate to look up
request method: GET or POST

Result

A single number giving the elevation in meters. Ocean areas are masked as "no data" and returned as -32768.

Example

XML JSON TXT

The plain-text variant also accepts lists of points via lats/lngs - up to 20 points per call free, 2000 on the premium service.

Elevation - SRTM3

Shuttle Radar Topography Mission data, captured aboard Space Shuttle Endeavour in February 2000, covering land between 60°N and 56°S at roughly 90m (3 arc-second) resolution.

Data voids in the original files have been filled in by CGIAR-CSI.

Url: http://api.geonames.org/srtm3?

Parameters

lat, lng - the coordinate to look up
request method: GET or POST

Result

A single number giving the elevation in meters. Ocean areas are masked as "no data" and returned as -32768.

Example

XML JSON TXT

The plain-text variant also accepts lists of points via lats/lngs - up to 20 points per call free, 2000 on the premium service.

Timezone

Url: http://api.geonames.org/timezone?

Parameters

lat, lng - the coordinate to look up
radius - buffer in km for the closest timezone in coastal areas
lang - language for the country name
date - date to compute sunrise/sunset for

Result

The timezone at the point, with its GMT offset (1 January) and DST offset (1 July).

countryCode: ISO country code
countryName: name (language can be set with the lang parameter)
timezoneId: the Olson timezone name - sufficient to resolve DST rules in most programming environments
time: the local current time
sunset: local sunset time
sunrise: local sunrise time
rawOffset: hours to add to UTC for standard time in this zone (unaffected by DST)
gmtOffset: offset to GMT at 1 January (deprecated)
dstOffset: offset to GMT at 1 July (deprecated)

Example

XML JSON