GeoNames Search Webservice

Webservice Description

Url	»	api.geonames.org/search?
Result	»	returns the names found for the searchterm as xml or json document, the search is using an AND operator

Parameter	Value	Description
q	string (q,name or name_equals required)	search over all attributes of a place : place name, country name, continent, admin codes,... (Important:urlencoded utf8)
name	string (q,name or name_equals required)	place name only(Important:urlencoded utf8)
name_equals	string (q,name or name_equals required)	exact place name
name_startsWith	string (optional)	place name starts with given characters
maxRows	integer (optional)	the maximal number of rows in the document returned by the service. Default is 100, the maximal allowed value is 1000.
startRow	integer (optional)	Used for paging results. If you want to get results 30 to 40, use startRow=30 and maxRows=10. Default is 0, the maximal allowed value is 5000 for the free services and 25000 for the premium services
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 (option), two letter country code ISO-3166	records from the countryBias are listed first
continentCode	string : continent code : AF,AS,EU,NA,OC,SA,AN (optional)	restricts the search for toponym of the given continent.
adminCode1, adminCode2, adminCode3, adminCode4, adminCode5	string : admin code (optional)	code of administrative subdivision
featureClass	character A,H,L,P,R,S,T,U,V (optional)	featureclass(es) (default= all feature classes); this parameter may occur more than once, example: featureClass=P&featureClass=A
featureCode	string (optional)	featurecode(s) (default= all feature codes); this parameter may occur more than once, example: featureCode=PPLC&featureCode=PPLX
cities	string (optional)	optional filter parameter with three possible values 'cities1000', 'cities5000','cities15000' used to categorize the populated places into three groups according to size/relevance. See the download readme for further infos
lang	string ISO-639 2-letter language code; en,de,fr,it,es,zh,zh-Hant... (optional)	place name and country name will be returned in the specified language. Default is English. With the pseudo language code 'local' the local language will be returned. Feature classes and codes are only available in English and Bulgarian. Any help in translating is welcome.
type	string xml,json,rdf	the format type of the returned document, default = xml
style	string SHORT,MEDIUM,LONG,FULL (optional)	verbosity of returned xml document, default = MEDIUM
isNameRequired	boolean (optional)	At least one of the search term needs to be part of the place name. Example : A normal search for Berlin will return all places within the state of Berlin. If we only want to find places with 'Berlin' in the name we set the parameter isNameRequired to 'true'. The difference to the name_equals parameter is that this will allow searches for 'Berlin, Germany' as only one search term needs to be part of the name.
tag	string (optional)	search for toponyms tagged with the specified tag
operator	string (optional)	default is 'AND', with the operator 'OR' not all search terms need to be matched by the response
charset	string (optional)	default is 'UTF8', defines the encoding used for the document returned by the web service.
fuzzy	float (optional)	default is '1', defines the fuzziness of the search terms. float between 0 and 1. The search term is only applied to the name attribute.
east,west,north,south	float (optional)	bounding box, only features within the box are returned
searchlang	string (optional)	in combination with the name parameter, the search will only consider names in the specified language. Used for instance to query for IATA airport codes.
orderby	string (optional)[population,elevation,relevance]	in combination with the name_startsWith, if set to 'relevance' than the result is sorted by relevance.
inclBbox	string (option) [true]	include Bbox info, regardelss of style setting. (normally only included with style=FULL

Examples

XML
Example 1 : http://api.geonames.org/search?q=london&maxRows=10&username=demo

Example 2 : http://api.geonames.org/search?q=london&maxRows=10&style=LONG&lang=es&username=demo

Example 3 bounding box : http://api.geonames.org/search?q=london&south=0&north=70&west=-120&east=-10&maxRows=10&username=demo

JSON
http://api.geonames.org/searchJSON?q=london&maxRows=10&username=demo

JSON is easier to use in Javascript than XML, as a browser security feature will no allow you to call an xml service from an other domain. A simple example using the json service on googlemaps is here

'name' and 'toponymName'
The response returns two name attributes. The 'name' attribute is a localized name, the preferred name in the language passed in the optional 'lang' parameter or the name that triggered the response in a 'startWith' search. The attribute 'toponymName' is the main name of the toponym as displayed on the google maps interface page or in the geoname file in the download. The 'name' attribute is derived from the alternate names.

Fuzzy Search
With the parameter 'fuzzy' the search will find results even if the search terms are incorrectly spelled. Example: http://api.geonames.org/search?q=londoz&fuzzy=0.8&username=demo

Reverse Geocoding
Reverse geocoding is the process of finding a place name for a given latitude and longitude. GeoNames has a wide range of reverse geocoding webservices.

RDF - Semantic Web
http://api.geonames.org/search?q=london&maxRows=10&type=rdf&username=demo

With the parameter type=rdf the search service returns the result in RDF format defined by the GeoNames Semantic Web Ontology.

Tags
GeoNames is using a simple tagging system. Every user can tag places. In contrast to the feature codes and feature classes which are one-dimensional (a place name can only have one feature code) several tags can be used for each place name. It is an additional categorization mechanism where the simple classification with feature codes is not sufficient.

I have tagged a place with the tag 'skiresort'. You can search for tags with the search : http://www.geonames.org/search.html?q=skiresort
If you only want to search for a tag and not for other occurrences of the term (in case you tag something with 'spain' for example), then you add the attribute 'tags:' to the search term : http://www.geonames.org/search.html?q=tags:skiresort

And if you want to search for tags of a particular user (or your own) then you append '@username' to the tag. Like this :
http://www.geonames.org/search.html?q=tags:skiresort@marc

With the API the the call looks like this:
http://api.geonames.org/search?tag=skiresort@marc&username=demo