GeonamesCache

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.

Installation

pip install geonamescache

Usage

A simple usage example:

import geonamescache

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

Settings

Cities dataset

When creating a GeonamesCache you can set the min_city_population parameter to either of 500, 1000, 5000 or the default 15000. The smaller the minimum popluation the more cities are included in the cities dataset.

New in version 1.4

Methods

Currently geonamescache provides the following methods, that 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()

In addition you can search for cities by name.

• search_cities('NAME', case_sensitive=True)

This function returns a list of city records that match the given NAME.

• By default the alternatenames attribute is searched for matches.
• By default the search is case sensitive, it can be made case insensitive by changing case_sensitive to False.

Mappers

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

Contributing

Please write test(s) for any new feature. If you wish to build the data from scratch, run make dl and make json.