GeoNames Web Services Documentation
GeoNames is mainly using REST webservices.Important:
- Do not use the 'demo' account for your app or your tests. It is only meant for the sample links on the documentation pages. Create your own account instead.
- The parameter 'username' needs to be passed with each request. The username for your application can be registered here. You will then receive an email with a confirmation link and after you have confirmed the email you can enable your account for the webservice on your account page
- Don't forget to url encode string parameters containing special characters or spaces. (Faq entry on url encoding)
- Use the JSON services if you want to use GeoNames from javascript, as most browsers do not allow to call xml services from ANOTHER server.
- all web services on one table.
- Secure endpoint available at secure.geonames.org
- client libraries
- Service Level Agreement is available for our commercial web services.
- credits per request
- Exceptions - error handling
Postal Code restrictions:
- For Canada we have only the first letters of the full postal codes (for copyright reasons)
- For Ireland we have only the first letters of the full postal codes (for copyright reasons)
- For Malta we have only the first letters of the full postal codes (for copyright reasons)
- The Argentina data file contains 4-digit postal codes which were replaced with a new system in 1999.
- For Brazil only major postal codes are available (only the codes ending with -000 and the major code per municipality).
Webservices
GeoNames search
Webservice for the GeoNames full text search in xml and json format. See the service description for details.Postal Code Search
| Url | » | api.geonames.org/postalCodeSearch? |
| Result | » | returns a list of postal codes and places for the placename/postalcode query as xml document For the US the first returned zip code is determined using zip code area shapes, the following zip codes are based on the centroid. For all other supported countries all returned postal codes are based on centroids. |
| 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) | all fields : placename,postal code, country, admin name (Important:urlencoded utf8) |
| placename_startsWith | string | the first characters of a place name |
| country | string : country code, ISO-3166 (optional) | Default is all countries. The country parameter may occur more than once, example: country=FR&country=GP |
| countryBias | string | records from the countryBias are listed first |
| maxRows | integer (optional) | the maximal number of rows in the document returned by the service. Default is 10 |
| style | string SHORT,MEDIUM,LONG,FULL (optional) | verbosity of returned xml document, default = MEDIUM |
| operator | string AND,OR (optional) | the operator 'AND' searches for all terms in the placename parameter, the operator 'OR' searches for any term, default = AND |
| charset | string (optional) | default is 'UTF8', defines the encoding used for the document returned by the web service. |
| isReduced | true or false (optional) | default is 'false', when set to 'true' only the UK outer codes respectivel the NL 4-digits are returned. Attention: the default value on the commercial servers is currently set to 'true'. It will be changed later to 'false'. |
| east,west,north,south | float (optional) | bounding box, only features within the box are returned |
Example http://api.geonames.org/postalCodeSearch?postalcode=9011&maxRows=10&username=demo
This service is also available in JSON format : http://api.geonames.org/postalCodeSearchJSON?postalcode=9011&maxRows=10&username=demo
Placename lookup with postalcode (JSON)
Webservice Type : REST /JSONUrl : api.geonames.org/postalCodeLookupJSON?
Parameters : postalcode,country ,maxRows (default = 20),callback, charset (default = UTF-8)
Result : returns a list of places for the given postalcode in JSON format, sorted by postalcode,placename
Example http://api.geonames.org/postalCodeLookupJSON?postalcode=6600&country=AT&username=demo
Details for this service with an ajax step by step example for placename autocomplete
Find nearby postal codes / reverse geocoding
This service comes in two flavors. You can either pass the lat/long or a postalcode/placename.
Webservice Type : REST
Url : api.geonames.org/findNearbyPostalCodes?
Parameters :
lat,lng, radius (in km), maxRows (default = 5),style (verbosity : SHORT,MEDIUM,LONG,FULL), country (default = all countries), localCountry (in border areas this parameter will restrict the search on the local country, value=true), isReduced=true to get only the first part of the code (GB and NL)
or
postalcode,country, radius (in Km), maxRows (default = 5)
Limits: 30km radius (free service), 160km (premium service), 500 maxRows (free service) and 2500 maxRows for the premium service.
Result : returns a list of postalcodes and places for the lat/lng query as xml document. The result is sorted by distance. For Canada the FSA is returned (first 3 characters of full postal code)
Example:
http://api.geonames.org/findNearbyPostalCodes?lat=47&lng=9&username=demo
or
api.geonames.org/findNearbyPostalCodes?postalcode=8775&country=CH&radius=10&username=demo
This service is also available in JSON format : api.geonames.org/findNearbyPostalCodesJSON?postalcode=8775&country=CH&radius=10&username=demo
[more reverse geocoding webservices]
Postal code country info
Webservice Type : RESTUrl : api.geonames.org/postalCodeCountryInfo?
Result : countries for which postal code geocoding is available.
Example : http://api.geonames.org/postalCodeCountryInfo?username=demo
Find nearby populated place / reverse geocoding
Webservice Type : RESTUrl : api.geonames.org/findNearbyPlaceName?
Parameters : lat,lng,
lang: language of returned 'name' element (the pseudo language code 'local' will return it in local language),
radius: radius in km (optional), maxRows: max number of rows (default 10)
style: SHORT,MEDIUM,LONG,FULL (default = MEDIUM), verbosity of returned xml document
localCountry: in border areas this parameter will restrict the search on the local country, value=true
cities: optional filter parameter with three possible values 'cities1000', 'cities5000','cities15000'. See the download readme for further infos
Result : returns the closest populated place (feature class=P) for the lat/lng query as xml document. The unit of the distance element is 'km'.
Example:
http://api.geonames.org/findNearbyPlaceName?lat=47.3&lng=9&username=demo
This service is also available in JSON format :
http://api.geonames.org/findNearbyPlaceNameJSON?lat=47.3&lng=9&username=demo
Find nearby toponym / reverse geocoding
Webservice Type : RESTUrl : api.geonames.org/findNearby?
Parameters : lat,lng, featureClass,featureCode, radius: radius in km (optional), maxRows : max number of rows (default 10)
The parameter featureCode may be used several times, to exclude a featureCode you can use 'featureCode!='
style : SHORT,MEDIUM,LONG,FULL (default = MEDIUM), verbosity of returned xml document
localCountry: in border areas this parameter will restrict the search on the local country, value=true
Result : returns the closest toponym for the lat/lng query as xml document
Example:
http://api.geonames.org/findNearby?lat=47.3&lng=9&username=demo
This service is also available in JSON format :
http://api.geonames.org/findNearbyJSON?lat=47.3&lng=9&username=demo
Extended Find nearby toponym / reverse geocoding
Webservice Type : RESTUrl : api.geonames.org/extendedFindNearby?
Parameters : lat,lng
Result : returns the most detailed information available for the lat/lng query as xml document
It is a combination of several services. Example:
In the US it returns the address information.
In other countries it returns the hierarchy service: http://api.geonames.org/extendedFindNearby?lat=47.3&lng=9&username=demo
On oceans it returns the ocean name.
[more reverse geocoding webservices]
get geoNames feature for geoNameId
Webservice Type : RESTUrl : api.geonames.org/get?
Parameters : geonameId, lang (optional), style (optional)
Result : returns the attribute of the geoNames feature with the given geonameId as xml document
Example:
http://api.geonames.org/get?geonameId=1&username=demo.
Place Hierarchy Webservices
Children
Hierarchy
Siblings
Neighbours
Wikipedia Webservices
Find nearby Wikipedia Entries / reverse geocoding
Wikipedia full text search
JSON Webservices
Cities and Placenames
Recent Earthquakes
Weather Stations with most recent Weather Observation
Placename lookup with postalcode
Other Webservices
RSS to GeoRSS Conversion
Details on RSS to GeoRSS converter.Semantic Web Webservices
Details on GeoNames Semantic Web services.Country Info (Bounding Box, Capital, Area in square km, Population)
Webservice Type : RESTUrl : api.geonames.org/countryInfo?
Parameters : country (default = all countries)
lang : ISO-639-1 language code (en,de,fr,it,es,...) (default = english)
Result : Country information : Capital, Population, Area in square km, Bounding Box of mainland (excluding offshore islands)
Example : http://api.geonames.org/countryInfo?username=demo
An other countryInfo service is available as csv output :
Example : http://api.geonames.org/countryInfoCSV?lang=it&country=DE&username=demo
CountryCode / reverse geocoding
The iso country code of any given point.
Webservice Type : REST
Url : api.geonames.org/countryCode?
Parameters : lat,lng, type, lang, radius (buffer in km for closest country in coastal areas, a positive buffer expands the positiv area whereas a negative buffer reduces it);
Result : returns the iso country code for the given latitude/longitude
With the parameter type=xml this service returns an xml document with iso country code and country name. The optional parameter lang can be used to specify the language the country name should be in. JSON output is produced with type=JSON
Example http://api.geonames.org/countryCode?lat=47.03&lng=10.2&username=demo
[more reverse geocoding webservices]
Country Subdivision / reverse geocoding
The iso country code and the administrative subdivision of any given point.
Webservice Type : REST
Url : api.geonames.org/countrySubdivision?
Parameters : lat,lng, lang (default= names in local language), radius (buffer in km for closest country in coastal areas, a positive buffer expands the positiv area whereas a negative buffer reduces it),level (level of ADM);
Result : returns the country and the administrative subdivison (state, province,...) for the given latitude/longitude
Example http://api.geonames.org/countrySubdivision?lat=47.03&lng=10.2&username=demo
With the parameters 'radius' and 'maxRows' you get the closest subdivisions ordered by distance :
api.geonames.org/countrySubdivision?lat=47.03&lng=10.2&maxRows=10&radius=40
This service is also available in JSON format : api.geonames.org/countrySubdivisionJSON?lat=47.03&lng=10.2&username=demo
Ocean / reverse geocoding
The name of the ocean or sea.
Webservice Type : REST
Url : api.geonames.org/ocean?
Parameters : lat,lng, radius (optional)
Result : returns the ocean or sea for the given latitude/longitude
The oceans returned by the service are listed here.
Example http://api.geonames.org/ocean?lat=40.78343&lng=-43.96625&username=demo
This service is also available in JSON format : api.geonames.org/oceanJSON?lat=40.78343&lng=-43.96625&username=demo
Neighbourhood / reverse geocoding
The neighbourhood for US cities. Data provided by Zillow under cc-by-sa license.
Webservice Type : REST
Url : api.geonames.org/neighbourhood?
Parameters : lat,lng
Result : returns the neighbourhood for the given latitude/longitude
Example http://api.geonames.org/neighbourhood?lat=40.78343&lng=-73.96625&username=demo
This service is also available in JSON format : api.geonames.org/neighbourhoodJSON?lat=40.78343&lng=-73.96625&username=demo
[more reverse geocoding webservices]
Elevation - SRTM1
Webservice Type : RESTUrl : api.geonames.org/srtm1?
Parameters : lat,lng;
request method: GET or POST
sample area: ca 30m x 30m Result : a single number giving the elevation in meters according to srtm1, ocean areas have been masked as "no data" and have been assigned a value of -32768
Example http://api.geonames.org/srtm1?lat=50.01&lng=10.2&username=demo
This service is also available in XML and JSON format :api.geonames.org/srtm1XML?lat=50.01&lng=10.2&username=demo api.geonames.org/srtm1JSON?lat=50.01&lng=10.2&username=demo
The text version of the service also accepts a list of lat/lng for the parameters 'lats' and 'lngs'. On the free server the number of points per call is limited to 20, for the premium service the limit is 2000:http://api.geonames.org/srtm1?lats=50.01,51.01&lngs=10.2,11.2&username=demo
Elevation - SRTM3
Shuttle Radar Topography Mission (SRTM) elevation data. SRTM consisted of a specially modified radar system that flew onboard the Space Shuttle Endeavour during an 11-day mission in February of 2000. The dataset covers land areas between 60 degrees north and 56 degrees south.This web service is using SRTM3 data with data points located every 3-arc-second (approximately 90 meters) on a latitude/longitude grid. Data voids in the original SRTM files have been filled by cgiar. Thanks to Andy Jarvis and Cgiar to allow GeoNames to use the processed data.
Documentation : cgiar-csi,Nasa
The astergdem data has finer resolution, but is not processed. The srtm3v4 data does not have the same resolution as the astergem data, but it is processed. This means holes and data errors have been corrected.
Webservice Type : REST
Url : api.geonames.org/srtm3?
Parameters : lat,lng;
request method: GET or POST
sample area: ca 90m x 90m
Result : a single number giving the elevation in meters according to srtm3, ocean
areas have been masked as "no data" and have been assigned a value of -32768
Example http://api.geonames.org/srtm3?lat=50.01&lng=10.2&username=demo
This service is also available in XML and JSON format :api.geonames.org/srtm3XML?lat=50.01&lng=10.2&username=demo api.geonames.org/srtm3JSON?lat=50.01&lng=10.2&username=demo
The text version of the service also accepts a list of lat/lng for the parameters 'lats' and 'lngs'. On the free server the number of points per call is limited to 20, for the premium service the limit is 2000:http://api.geonames.org/srtm3?lats=50.01,51.01&lngs=10.2,11.2&username=demo
Elevation - Aster Global Digital Elevation Model V2 2011
Webservice Type : RESTUrl : api.geonames.org/astergdem?
Parameters : lat,lng;
request method: GET or POST
sample are: ca 30m x 30m, between 83N and 65S latitude. Result : a single number giving the elevation in meters according to aster gdem, ocean areas have been masked as "no data" and have been assigned a value of -32768
Example http://api.geonames.org/astergdem?lat=50.01&lng=10.2&username=demo
ASTER GDEM is a product of METI and NASA.
This service is also available in XML and JSON format : api.geonames.org/astergdemXML?lat=50.01&lng=10.2&username=demo and api.geonames.org/astergdemJSON?lat=50.01&lng=10.2&username=demo
The text version of the service also accepts a list of lat/lng for the parameters 'lats' and 'lngs'. On the free server the number of points per call is limited to 20, for the premium service the limit is 2000. http://api.geonames.org/srtm3?lats=50.01,51.01&lngs=10.2,11.2&username=demo
Elevation - GTOPO30
GTOPO30 is a global digital elevation model (DEM) with a horizontal grid spacing of 30 arc seconds (approximately 1 kilometer). GTOPO30 was derived from several raster and vector sources of topographic information. Documentation : USGS Gtopo30
Webservice Type : REST
Url : api.geonames.org/gtopo30?
Parameters : lat,lng;
sample area: ca 1km x 1km
Result : a single number giving the elevation in meters according to gtopo30, ocean
areas have been masked as "no data" and have been assigned a value of -9999
Example http://api.geonames.org/gtopo30?lat=47.01&lng=10.2&username=demo
This service is also available in JSON format : http://api.geonames.org/gtopo30JSON?lat=47.01&lng=10.2&username=demo
Timezone
Webservice Type : RESTUrl : api.geonames.org/timezone?
Parameters : lat,lng, radius (buffer in km for closest timezone in coastal areas),lang (for countryName), date (date for sunrise/sunset);
Result : the timezone at the lat/lng with gmt offset (1. January) and dst offset (1. July)
Example http://api.geonames.org/timezone?lat=47.01&lng=10.2&username=demo
This service is also available in JSON format : http://api.geonames.org/timezoneJSON?lat=47.01&lng=10.2&username=demo
Element:
countryCode: ISO countrycode
countryName: name (language can be set with param lang)
timezoneId: name of the timezone (according to olson), this information is sufficient to work with the timezone and defines DST rules, consult the documentation of your development environment. Many programming environments include functions based on the olson timezoneId (example java TimeZone)
time: the local current time
sunset: sunset local time (date)
sunrise: sunrise local time (date)
rawOffset: the amount of time in hours to add to UTC to get standard time in this time zone. Because this value is not affected by daylight saving time, it is called raw offset.
gmtOffset: offset to GMT at 1. January (deprecated)
dstOffset: offset to GMT at 1. July (deprecated)
Support GeoNames with a donation :
