GeoNames Web Service Documentation
GeoNames is mainly using REST webservices.
- Don't use the
demoaccount in your own app or tests - it's only for the sample links on this page. Register your own free account instead. - The
usernameparameter 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.
- 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.
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.
Examples
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.
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.
Examples
Country Info (bounding box, capital, area, population)
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).
Examples
Country Subdivision / reverse geocoding
The ISO country code and administrative subdivision (state, province, ...) for any given point.
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.
Examples
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.
Parameters
- lat, lng - the coordinate to look up
Result
The most detailed information available for the given point.
Example
Find Nearby Toponym / reverse geocoding
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.
Examples
Find Nearby Populated Place / reverse geocoding
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.
Examples
Find Nearby Postal Codes / reverse geocoding
Comes in two flavors: pass either a lat/lng, or a postalcode/placename.
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.
Examples
Get GeoNames Feature for geonameId
Parameters
- geonameId - required
- lang - optional
- style - optional
Result
The attributes of the GeoNames feature with the given geonameId.
Examples
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).
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.
Examples
Neighbourhood / reverse geocoding
Neighbourhoods for US cities. Data provided by Zillow under a CC BY-SA license.
Parameters
- lat, lng - the coordinate to look up
Result
The neighbourhood for the given point.
Examples
Ocean / reverse geocoding
The name of the ocean or sea at a given point.
See also: All the oceans and seas on a map.
Parameters
- lat, lng - the coordinate to look up
- radius - optional
Result
The ocean or sea for the given point.
Examples
Postal Code Country Info
Result
The list of countries for which postal-code geocoding is available.
Examples
Placename Lookup with Postal Code (JSON)
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
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.
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.
Examples
Elevation - SRTM1
Sample area ca. 30m x 30m.
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.
Examples
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.
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.
Examples
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
See also: The timezones of the world on a map.
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 standard offset and the local time, sunrise and sunset.
countryCode: ISO country codecountryName: name (language can be set with the lang parameter)timezoneId: the Olson timezone name - sufficient to resolve DST rules in most programming environmentstime: the local current timesunset: local sunset timesunrise: local sunrise timerawOffset: hours to add to UTC for standard time in this zone (unaffected by DST)
Examples
time, sunrise and sunset are local to the place, in the form "yyyy-MM-dd HH:mm". The top-level sunrise and sunset are always for today; with the date parameter, the times for that date are returned in the dates array.
There are no sunrise or sunset values on days when the sun does not rise or set (polar day and night), nor where no timezone is found.