Skip to main content

Geonames data for continents, cities and US states.

Project description

A Python library that provides functions to retrieve names, ISO and FIPS codes of continents, countries as well as US states and counties as Python dictionaries. The country and city datasets also include population and geographic data.

Geonames data is obtained from GeoNames.


To install geonamescache, run:

$ sudo pip install geonamescache

Or, if necessary:

$ sudo easy_install geonamescache


A simple usage example:

import geonamescache

gc = geonamescache.GeonamesCache()
countries = gc.get_countries()
# print countries dictionary
# you really wanna do something more useful with the data...


Currently geonamescache provides the following methods, that all return dictionaries with the requested data:

  • get_continents()
  • get_countries()
  • get_us_states()
  • get_cities()
  • get_countries_by_names()
  • get_us_states_by_names()
  • get_cities_by_name(name)
  • get_us_counties()


The mappers module provides function(s) to map data properties. Currently you can create a mapper that maps country properties, e. g. the name property to the iso3 property, to do so you’d write the following code:

from geonamescache.mappers import country
mapper = country(from_key='name', to_key='iso3')

iso3 = mapper('Spain') # iso3 is assigned ESP


  1. Fork the repository on GitHub
  2. Commit your changes to the develop branch
  3. Write test(s) for any new feature
  4. Push your changes and send a pull request

If you wish to build the data from scratch, you can run the fabric file, Before you can run this, you need to create an account in the Geonames system, then activate your account for API usage. Once you’ve created your account, you can run:

fab dl # Download the geonames data to the data directory GEONAMES_USER=<your-username-here> fab tojson # Convert the downloaded data to json

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
geonamescache-1.0.1-py3-none-any.whl (775.4 kB) Copy SHA256 hash SHA256 Wheel 3.6
geonamescache-1.0.1.tar.gz (740.8 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page