# GeonamesCache
[](https://pypi.python.org/pypi/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](http://www.geonames.org/).
## 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, 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`.
Raw data
{
"_id": null,
"home_page": "https://github.com/yaph/geonamescache",
"name": "geonamescache",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Ramiro G\u00f3mez",
"author_email": "code@ramiro.org",
"download_url": "https://files.pythonhosted.org/packages/3c/5a/2794a754c6e1f8c2a5699883958e410856f3976e18709a1f9b6f5144e484/geonamescache-2.0.0.tar.gz",
"platform": null,
"description": "# GeonamesCache\n\n[](https://pypi.python.org/pypi/geonamescache)\n\nA 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.\n\nGeonames data is obtained from [GeoNames](http://www.geonames.org/).\n\n## Installation\n\n pip install geonamescache\n\n## Usage\n\nA simple usage example:\n\n import geonamescache\n\n gc = geonamescache.GeonamesCache()\n countries = gc.get_countries()\n # print countries dictionary\n print(countries)\n # you really wanna do something more useful with the data...\n\n## Settings\n\n### Cities dataset\n\nWhen 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.\n\n*New in version 1.4*\n\n## Methods\n\nCurrently geonamescache provides the following methods, that return dictionaries with the requested data:\n\n* get\\_continents()\n* get\\_countries()\n* get\\_us\\_states()\n* get\\_cities()\n* get\\_countries\\_by\\_names()\n* get\\_us\\_states\\_by\\_names()\n* get\\_cities\\_by\\_name(name)\n* get\\_us\\_counties()\n\nIn addition you can search for cities by name.\n\n* search\\_cities(\\'NAME\\', case\\_sensitive=True, contains\\_search=True)\n\nThis function returns a list of city records that match the given `NAME`.\n\n* By default the `alternatenames` attribute is searched for matches.\n* By default the search is case insensitive, it can be made case sensitive by changing `case_sensitive` to True.\n* By default the search is contains, it can be made exact equality by changing `contains_search` to False.\n\n## Mappers\n\nThe 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:\n\n from geonamescache.mappers import country\n mapper = country(from_key='name', to_key='iso3')\n\n iso3 = mapper('Spain') # iso3 is assigned ESP\n\n## Contributing\n\nPlease write test(s) for any new feature. If you wish to build the data from scratch, run `make dl` and `make json`.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Geonames data for continents, cities and US states.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/yaph/geonamescache"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e8a6555e3c3ed1fcadf229dcfb41b92d51eb0c7623d42290e1d6925ac383b33",
"md5": "678608b8b49d16db8a5ba984be77dcb6",
"sha256": "24fdaaeaf236f88786dec8c0ab55447f5f7f95ef6c094e79fa9ef74114ea1fe2"
},
"downloads": -1,
"filename": "geonamescache-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "678608b8b49d16db8a5ba984be77dcb6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26622351,
"upload_time": "2023-07-03T21:34:43",
"upload_time_iso_8601": "2023-07-03T21:34:43.994197Z",
"url": "https://files.pythonhosted.org/packages/2e/8a/6555e3c3ed1fcadf229dcfb41b92d51eb0c7623d42290e1d6925ac383b33/geonamescache-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3c5a2794a754c6e1f8c2a5699883958e410856f3976e18709a1f9b6f5144e484",
"md5": "fa45340efcfa06aa93b15fca4a1cec9a",
"sha256": "fa1eed0b5b591b478ad81979081ac15b37aa6a1c00bb02431a570688e5c2ecc9"
},
"downloads": -1,
"filename": "geonamescache-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fa45340efcfa06aa93b15fca4a1cec9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25565852,
"upload_time": "2023-07-03T21:40:33",
"upload_time_iso_8601": "2023-07-03T21:40:33.107232Z",
"url": "https://files.pythonhosted.org/packages/3c/5a/2794a754c6e1f8c2a5699883958e410856f3976e18709a1f9b6f5144e484/geonamescache-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-03 21:40:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yaph",
"github_project": "geonamescache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "geonamescache"
}
JSON
