GeoNames Web Service Documentation

GeoNames Web Services Documentation

GeoNames is mainly using REST webservices.

Important:

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.
client libraries
Service Level Agreement is available for our commercial web services.

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	»	ws.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.
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.

Example http://ws.geonames.org/postalCodeSearch?postalcode=9011&maxRows=10

This service is also available in JSON format : http://ws.geonames.org/postalCodeSearchJSON?postalcode=9011&maxRows=10

[more on free-geocoding ...]

Placename lookup with postalcode (JSON)

Webservice Type : REST /JSON
Url : ws.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
Example http://ws.geonames.org/postalCodeLookupJSON?postalcode=6600&country=AT

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 : ws.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)
or
postalcode,country, radius (in Km), maxRows (default = 5)
Result : returns a list of postalcodes and places for the lat/lng query as xml document
Example:
http://ws.geonames.org/findNearbyPostalCodes?lat=47&lng=9
or
ws.geonames.org/findNearbyPostalCodes?postalcode=8775&country=CH&radius=10

This service is also available in JSON format : ws.geonames.org/findNearbyPostalCodesJSON?postalcode=8775&country=CH&radius=10

[more reverse geocoding webservices]

Postal code country info

Webservice Type : REST
Url : ws.geonames.org/postalCodeCountryInfo?
Result : countries for which postal code geocoding is available.
Example : http://ws.geonames.org/postalCodeCountryInfo?

Find nearby populated place / reverse geocoding

Webservice Type : REST
Url : ws.geonames.org/findNearbyPlaceName?
Parameters : lat,lng, radius: radius in km (optional), maxRows : max number of rows (default 10)
style : SHORT,MEDIUM,LONG,FULL (default = MEDIUM), verbosity of returned xml document
Result : returns the closest populated place for the lat/lng query as xml document
Example:
http://ws.geonames.org/findNearbyPlaceName?lat=47.3&lng=9

This service is also available in JSON format :
http://ws.geonames.org/findNearbyPlaceNameJSON?lat=47.3&lng=9

Find nearby toponym / reverse geocoding

Webservice Type : REST
Url : ws.geonames.org/findNearby?
Parameters : lat,lng, featureClass,featureCode, radius: radius in km (optional), maxRows : max number of rows (default 10)
style : SHORT,MEDIUM,LONG,FULL (default = MEDIUM), verbosity of returned xml document
Result : returns the closest toponym for the lat/lng query as xml document
Example:
http://ws.geonames.org/findNearby?lat=47.3&lng=9

This service is also available in JSON format :
http://ws.geonames.org/findNearbyJSON?lat=47.3&lng=9

Extended Find nearby toponym / reverse geocoding

Webservice Type : REST
Url : ws.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://ws.geonames.org/extendedFindNearby?lat=47.3&lng=9
On oceans it returns the ocean name.

[more reverse geocoding webservices]

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 : REST
Url : ws.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://ws.geonames.org/countryInfo?

An other countryInfo service is available as csv output :
Example : http://ws.geonames.org/countryInfoCSV?lang=it&country=DE

CountryCode / reverse geocoding

The iso country code of any given point.

Webservice Type : REST
Url : ws.geonames.org/countryCode?
Parameters : lat,lng, type, lang, radius (buffer in km for closest country in coastal areas);
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://ws.geonames.org/countryCode?lat=47.03&lng=10.2

[more reverse geocoding webservices]

Country Subdivision / reverse geocoding

The iso country code and the administrative subdivision of any given point.

Webservice Type : REST
Url : ws.geonames.org/countrySubdivision?
Parameters : lat,lng, lang (default= names in local language), radius (buffer in km for closest country in coastal areas);
Result : returns the country and the administrative subdivison (state, province,...) for the given latitude/longitude
Example http://ws.geonames.org/countrySubdivision?lat=47.03&lng=10.2

With the parameters 'radius' and 'maxRows' you get the closest subdivisions ordered by distance :
ws.geonames.org/countrySubdivision?lat=47.03&lng=10.2&maxRows=10&radius=40

This service is also available in JSON format : ws.geonames.org/countrySubdivisionJSON?lat=47.03&lng=10.2

Ocean / reverse geocoding

The name of the ocean or sea.

Webservice Type : REST
Url : ws.geonames.org/ocean?
Parameters : lat,lng
Result : returns the ocean or sea for the given latitude/longitude
Example http://ws.geonames.org/ocean?lat=40.78343&lng=-43.96625

This service is also available in JSON format : ws.geonames.org/oceanJSON?lat=40.78343&lng=-43.96625

Neighbourhood / reverse geocoding

The neighbourhood for US cities. Data provided by Zillow under cc-by-sa license.

Webservice Type : REST
Url : ws.geonames.org/neighbourhood?
Parameters : lat,lng
Result : returns the neighbourhood for the given latitude/longitude
Example http://ws.geonames.org/neighbourhood?lat=40.78343&lng=-73.96625

This service is also available in JSON format : ws.geonames.org/neighbourhoodJSON?lat=40.78343&lng=-73.96625

[more reverse geocoding webservices]

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. Documentation : Nasa

Webservice Type : REST
Url : ws.geonames.org/srtm3?
Parameters : lat,lng;
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://ws.geonames.org/srtm3?lat=50.01&lng=10.2

This service is also available in XML and JSON format :ws.geonames.org/srtm3XML?lat=50.01&lng=10.2 ws.geonames.org/srtm3JSON?lat=50.01&lng=10.2

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.

Elevation - Aster Global Digital Elevation Model

Webservice Type : REST
Url : ws.geonames.org/astergdem?
Parameters : lat,lng;
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 -9999
Example http://ws.geonames.org/astergdem?lat=50.01&lng=10.2

This service is also available in XML and JSON format : ws.geonames.org/astergdemXML?lat=50.01&lng=10.2 and ws.geonames.org/astergdemJSON?lat=50.01&lng=10.2

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.

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 Readme

Webservice Type : REST
Url : ws.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://ws.geonames.org/gtopo30?lat=47.01&lng=10.2

This service is also available in JSON format : http://ws.geonames.org/gtopo30JSON?lat=47.01&lng=10.2

Timezone

Webservice Type : REST
Url : ws.geonames.org/timezone?
Parameters : lat,lng;
Result : the timezone at the lat/lng with gmt offset (1. January) and dst offset (1. July)
Example http://ws.geonames.org/timezone?lat=47.01&lng=10.2

This service is also available in JSON format : http://ws.geonames.org/timezoneJSON?lat=47.01&lng=10.2

Element:
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.
time: the local current time
rawOffset: the amount of time in hours to add to UTC to get standard time in this time zone.
gmtOffset: offset to GMT at 1. January (deprecated)
dstOffset: offset to GMT at 1. July (deprecated)

GeoNames Webservice Spreadsheet

Barry Hunter from nearby.org.uk has compiled a spreadsheet with the GeoNames webservices.

Support GeoNames with a donation :