Repository files navigation

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 fromGeoNames.

pip install geonamescache

A simple example:

import geonamescachegc = geonamescache.GeonamesCache()print(gc.get_countries())

When creating aGeonamesCache you can set themin_city_population parameter to either of 500, 1000, 5000 or the default 15000. The smaller the minimum population the more cities are included in the cities dataset.

New in version 1.4

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, contains_search=True)

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

• By default thealternatenames attribute is searched for matches.
• By default the search is case insensitive, it can be made case sensitive by changingcase_sensitive to True.
• By default the search is contains, it can be made exact equality by changingcontains_search to False.

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

from geonamescache.mappers import countrymapper = country(from_key='name', to_key='iso3')iso3 = mapper('Spain') # iso3 is assigned ESP

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