yaph/geonamescache

geonamescache - a Python library for quick access to a subset of GeoNames data.

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 example:

import geonamescache

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

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 population 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, contains_search=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 insensitive, it can be made case sensitive by changing case_sensitive to True.
• By default the search is contains, it can be made exact equality by changing contains_search 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.

geonamescache's Issues

Various fields should be an int or float

In the cities database a bunch of fields are provided as strings. Can we convert these to an int?

For example:

{u'countrycode': u'US',
 u'geonameid': u'5385955',
 u'latitude': u'34.1064',
 u'longitude': u'-117.59311',
 u'name': u'Rancho Cucamonga',
 u'population': u'165269',
 u'timezone': u'America/Los_Angeles'},

Of these, geonameid and population could be ints, while lat/long could be floats.

Add mapper module in mappings

Add a mappers module with the following functions that return mappers:

• country: map country properties
• us_state: map us_state properties

get states from other countries

would it also be possible to query states/departments from other countries outside the USA?

[FEATURE REQUEST] type hints?

It'd be nice if this package had more type hints and .pyi files to get a better IDE experience when using the package under strict type checkers.

Would the package maintainer be okay with me providing a PR that adds type hints and .pyi files to the package?

I'd ensure type hints are compatible with Python >=3.8.

Document min_city_population

Better automate US states data retrieval

Write a Python scraper that stores data as JSON.

search_cities inconsistency

The function handles 'name' and 'alternatenames' differently, should these be brought in line with each other?

• For 'name' that is a string it will do a string in string search. So can be a partial match for example 'new york' will return 'new york city')
• For 'alternatenames' that is a list it will do a string in list search. So needs to be an exact match.

I am happy to implement bringing these two inline, however this would be a breaking functionality change unless you wish for it to be feature flagged (e.g. exact_match=None, that will keep the current difference but when set to true/false keeps them consistent)

Remove code that supports Python 2.7

• Use casefold and remove check for it in search_cities and corresponding test.

Call get_dataset_by_key with name of dataset, so there is no need for *_by_names methods

v 0.19 dropped counties?

I hope this wasn't intentional, but when I upgraded to the 0.19 version, the us_counties information disappeared. The latest code has it, but the version on pip doesn't?

Decoding JSON in GitHub workflow fails since changing to Git LFS (Large File Storage)

See https://stackoverflow.com/questions/70491037/how-i-can-use-github-lfs-together-with-large-size-json-server-json

Replace unittest with pytest

Create sphinx docs

Not all the cities

I tried to use the package but actually the cities in italy are around 8092 and not 603 as
len( [cities[key]['name'] for key in cities if cities[key]['countrycode'] == 'IT' ] )

Python 3 support

Getting a UnicodeDecodeError when trying to install with Python 3.5.

Thanks,
Dave

Include US state in cities data

I maintain my own private fork of geonamescache that, for cities, additionally extracts and includes the admin1code field. For US cities this corresponds to the state code, e.g. FL.

My use case is that I use this module to provide basic city-level geocoding to the users of a service I run, and US-based users seem to require the state code as part of the city name.

Is there a better way of achieving this mapping with the stock module? I may have missed something.

If not, is this the kind of contribution that would be welcome upstream?

Update to latest geonames data

Would it be possible to release an update on Pypi with latest geonames data?

I tried to figure out how to update the JSON files but could not see where they come from on the geonames website.

[

[FEATURE REQUEST] search_countries() method

Would it be possible to add alternate names for countries and a search_country() method, like it exists for cities?

How to get data with another language?

I need get data countries, state, cities in many language. How to do this?

Unable to find few City details.

Not found any result for "Alberta" , where as its present in Geonames.org.

Could you please let me know if there any workaround for this.

Thanks.

Adding the ability to search_cities with case insensitive search.

An example city of "Stoke-on-Trent" has multiple combinations of how this could be written, as the -on- is lower we can't use str.title() and there are other examples of joining words. One way this could be handled in the client is to lower every word apart from the first and last separated by the -. However it is probably easier for a case insensitive search.

If you agree with this change, I will send a pull request to add this. If you are happy for me to add this, would you like a feature flag like case_insensitive=False or be the default?

Various requirments are not required

In dev_requirements.txt there are a few items that aren't required:

numpy
python-dateutil
pytz
six

I could be mistaken, but I searched for all of these dependencies and these four don't seem to be used. I'll file a PR in a moment to purge them.

Getting cities by name through alternate names

In cities_by_name(), if the city name is Kiev, it would return an empty list but if the city name is Kyiv, it would return a list containing the city in Ukraine. Although both names pertain to the same city.

Would such enhancement be possible?

Convert README from restructured text to markdown

Analyze performance of get_cities_by_name

Possibly use generators.

Add country name mappings

Different names may be used to refer to countries. Assemble mappings from IPython notebooks and put them into mappings.py, e. g.:

country_names_to_iso3 = {
    'Alt name': 'alt',
    ...
}

Missing entries for some disputed areas

Baikonur
N. Cyprus
Somaliland