JSON Webservice

JSON Webservices

GeoNames offers most webservices in XML and JSON format. JSON has the advantage that is can be used to directly access the geonames webservice from javascript code, whereas using XML the browser will throw a security exception if an xml call to another webserver is made.

All JSON services accept an optional parameter 'callback' for a javascript function call and a parameter 'formatted=true' to format the output with linefeeds and indentation. The latter is useful to view the JSON result in a browser but should not be used in production usage (waste of bandwith).

JSON Examples :
Placename autocomplete
full text search on google maps

Places

Cities and Placenames

Webservice Type : REST
Url : api.geonames.org/citiesJSON?
Parameters :
north,south,east,west : coordinates of bounding box
callback : name of javascript function (optional parameter)
lang : language of placenames and wikipedia urls (default = en)
maxRows : maximal number of rows returned (default = 10)

Result : returns a list of cities and placenames in the bounding box, ordered by relevancy (capital/population). Placenames close together are filterered out and only the larger name is included in the resulting list.

Example : http://api.geonames.org/citiesJSON?north=44.1&south=-9.9&east=-22.4&west=55.2&lang=de&username=demo

This service is also available in XML output :
Example : http://api.geonames.org/cities?north=44.1&south=-9.9&east=-22.4&west=55.2&username=demo

Fulltext Search

Details full text search

Place Hierarchy Webservices

Children

Hierarchy

Siblings

Neighbours

Wikipedia

Find nearby Wikipedia Entries / reverse geocoding

Wikipedia Fulltext Search

Wikipedia Articles in Bounding Box

Postal Codes

Postal Code Search

Find nearby postal codes / reverse geocoding

Placename lookup with postalcode

Reverse Geocoding

Street/Address reverse geocoding for the US

Global street reverse geocoding

Country

Country Subdivision

Earthquakes

Recent Earthquakes

Webservice Type : REST
Url : api.geonames.org/earthquakesJSON?
Parameters :
north,south,east,west : coordinates of bounding box
callback : name of javascript function (optional parameter)
date : date of earthquakes 'yyyy-MM-dd', optional parameter, earthquakes older or equal the given date sorted by date,magnitude
minMagnitude : minimal magnitude, optional parameter
maxRows : maximal number of rows returned (default = 10)

Result : returns a list of earthquakes, ordered by magnitude

Example http://api.geonames.org/earthquakesJSON?north=44.1&south=-9.9&east=-22.4&west=55.2&username=demo

Weather

Weather data is provided in the METAR (METeorological Aerodrome Report) format.
Translations for weather conditions are available in English (default), German, Spanish, French, Italian, Czech, Dutch, Finnish, Swedish, Arabic, Portuguese, Hebrew, Polish, Russian and Bulgarian. Add the parameter 'lang=' with the language code for weather conditions in the desired language.

Help with the translation of METAR weather conditions is welcome.

Units:
Elevation = meter
Wind speed = Knots
Temperature = Celsius

datetime = UTC time

Weather Stations with most recent Weather Observation

Webservice Type : REST
Url : api.geonames.org/weatherJSON?
Parameters :
north,south,east,west : coordinates of bounding box
callback : name of javascript function (optional parameter)
maxRows : maximal number of rows returned (default = 10)

Result : returns a list of weather stations with the most recent weather observation

Example http://api.geonames.org/weatherJSON?north=44.1&south=-9.9&east=-22.4&west=55.2&username=demo

Weather Station with most recent weather observation

Webservice Type : REST
Url : api.geonames.org/weatherIcaoJSON?
Parameters :
ICAO : International Civil Aviation Organization (ICAO) code
callback : name of javascript function (optional parameter)

Result : returns the weather station and the most recent weather observation for the ICAO code

Example http://api.geonames.org/weatherIcaoJSON?ICAO=LSZH&username=demo

Weather Station with most recent weather observation / reverse geocoding

Webservice Type : REST
Url : api.geonames.org/findNearByWeatherJSON?
Parameters :
lat,lng : the service will return the station closest to this given point (reverse geocoding)
callback : name of javascript function (optional parameter)
radius: search radius, only weather stations within this radius are considered. Default is about 100km.

Result : returns a weather station with the most recent weather observation

Example http://api.geonames.org/findNearByWeatherJSON?lat=43&lng=-2&username=demo

An XML version is available : Example http://api.geonames.org/findNearByWeatherXML?lat=43&lng=-2&username=demo