GeoNames is mainly using REST APIs. It offers 40 different webservices, listed with examples in its overview

Geocoder supports the following ones:

  • (geocoding) retrieve GeoNames’s geocoded data from a query string, and various filters
  • (details) retrieve all geonames data for a given geonames_id
  • (children) retrieve the hierarchy of a given geonames_id
  • (hierarchy) retrieve all children for a given geonames_id


>>> import geocoder
>>> g = geocoder.geonames('New York', key='<USERNAME>')
>>> g.address
"New York City"
>>> g.geonames_id
>>> g.description
"city, village,..."
>>> g.population

Geonames web service support a lot of filters that you can use to refine your query. Here follows a list from the official documentation

  • ‘name’, ‘name_equals’, ‘name_startsWith’,
  • ‘maxRows’, ‘startRow’,
  • ‘country’, ‘countryBias’, ‘continentCode’,
  • ‘adminCode1’, ‘adminCode2’, ‘adminCode3’,
  • ‘featureClass’, ‘featureCode’,
  • ‘lang’, ‘type’, ‘style’, ‘fuzzy’,
  • ‘isNameRequired’, ‘tag’, ‘operator’, ‘charset’
  • ‘east’, ‘west’, ‘north’, ‘south’

They are all supported

>>> import geocoder
>>> g = geocoder.geonames('New York', key='<USERNAME>', featureClass='A')
>>> g.address
"New York"
>>> g.geonames_id
>>> g.description
"first-order administrative division"
>>> g.population

Multiple filters for some parameters

As pointed out in Geonames specs, the search (geocoding) service accepts multiple values for some parameters, namingly:

  • country
  • featureClass
  • featureCode

This is also supported by Geocoder, which will expect an array instead of the normal string.

>>> g = geocoder.geonames('Paris', maxRows=5, country=['FR', 'US'], key='<USERNAME>')
>>> print([(r.address, for r in g])
[('Paris', 'France'), ('Paris', 'United States'), ('Paris', 'France'), ('Paris', 'United States'), ('Paris', 'United States')]


As mentioned above, Geomanes allows the extra parameters ‘east’, ‘west’, ‘north’, ‘south’ to restrict the query to the therefore defined box.

>>> g = geocoder.geonames('Paris', key='<USERNAME>', east=-96.0, west=-95.0, north=33.5, south=33.0)
>>> g.address
'United States'

For consistency purpose, geocoder also accepts a ‘proximity’ parameter, which can be a bbox, bounds or a dictionnary with all directions. Please refer to this section for more details.

Details (inc. timezone, bbox)

This method requires a valid geonames_id, which you can get with the geocode method. It will fetchs all available information from geonames, including timezone and bbox.

g = geocoder.geonames(6094817, method='details', key='<USERNAME>')

>>> g.lng
>>> g.geonames_id
>>> g.address
>>> g.feature_class
>>> g.class_description
"city, village,..."
>>> g.code
>>> g.description
"capital of a political entity"
>>> g.continent
>>> g.country_geonames_id
>>> g.country_code
>>> g.state
>>> g.state_code
>>> g.state_geonames_id
>>> g.admin2
>>> g.admin3
>>> g.admin4
>>> g.admin5
>>> g.population
>>> g.srtm3
>>> g.wikipedia
>>> g.timeZoneId
>>> g.timeZoneName
>>> g.rawOffset
>>> g.dstOffset
>>> g.bbox
{'northeast': [45.58753415000007, -75.07957784899992], 'southwest': [44.962202955000066, -76.35400795899994]}

Children and Hierarchy

These two web services expect a geonames_id, which means you first need to make geocode your location. They will return multiple results most of the time, which you can access as described in the page ‘Access to geocoder results’.

>>> import geocoder
>>> g = geocoder.geonames('New York', key='<USERNAME>', method='children')
>>> c = geocoder.geonames(g.geoname_id, key='<USERNAME>', method='children')
>>> c.geojson
>>> h = geocoder.geonames(g.geoname_id, key='<USERNAME>', method='hierarchy')
>>> h.geojson

Command Line Interface

$ geocode 'New York City' --provider geonames

Environment Variables

To make sure your API key is store safely on your computer, you can define that API key using your system’s environment variables.

$ export GEONAMES_USERNAME=<Secret Username>


  • location: Your search location you want geocoded.
  • geonameid: The place you want details / children / hierarchy for.
  • key: (required) geonames username needs to be passed with each request.
  • maxRows: (default=1) Max number of results to fetch
  • proximity: Search within given area (bbox, bounds, or around latlng)
  • method: (default=geocode) Use the following:
    • geocode
    • details (mainly for administrive data and timezone)
    • timezone (alias of details)
    • children
    • hierarchy