GeonamesCache

https://github.com/yaph/geonamescache
Admin
GeonamesCache is a Python library that retrieves geographic data including continent, country,...
Tokens:22,525
Snippets:260
Trust Score:9.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install GeonamesCache

Source: https://github.com/yaph/geonamescache/blob/master/README.md

Install the library using pip.

```bash
pip install geonamescache
```

--------------------------------

### Install and Initialize Geonamescache

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Use pip to install the package and initialize the GeonamesCache class to access geographical data.

```python
# Install
pip install geonamescache

# Import and initialize
from geonamescache import GeonamesCache
gc = GeonamesCache()
```

--------------------------------

### Usage examples for country mapper

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/mappers.md

Various ways to initialize and use the country mapper for different attribute conversions and error handling.

```python
from geonamescache.mappers import country

# Create a name-to-ISO3 mapper (most common use case)
mapper = country(from_key='name', to_key='iso3')
iso3 = mapper('Spain')  # Returns 'ESP'
iso3 = mapper('Burma')  # Returns 'MMR' (applies name mapping)
iso3 = mapper('USA')    # Returns 'USA' (applies name mapping: USA -> United States)

# Create an ISO2-to-capital mapper
iso_to_capital = country(from_key='iso', to_key='capital')
capital = iso_to_capital('ES')  # Returns 'Madrid'
capital = iso_to_capital('FR')  # Returns 'Paris'

# Create a name-to-continent mapper
name_to_continent = country(from_key='name', to_key='continentcode')
continent = name_to_continent('Spain')  # Returns 'EU'
continent = name_to_continent('Japan')  # Returns 'AS'

# Create a name-to-population mapper (numeric output)
name_to_pop = country(from_key='name', to_key='population')
pop = name_to_pop('United States')  # Returns population as int

# Create a name-to-currency mapper
name_to_currency = country(from_key='name', to_key='currencycode')
currency = name_to_currency('France')  # Returns 'EUR'

# Chaining mappers to convert between different identifiers
iso2_to_iso3 = country(from_key='iso', to_key='iso3')
iso3 = iso2_to_iso3('ES')  # Returns 'ESP'

# Using the mapper with error handling
mapper = country(from_key='name', to_key='iso3')
result = mapper('NonexistentCountry')
if result is None:
    print("Country not found")

# Alternative country name variants are automatically mapped
mapper = country(from_key='name', to_key='iso')
mapper('The Netherlands')  # Returns 'NL' (mapped from 'Netherlands')
mapper('Czech Republic')   # Returns 'CZ' (mapped to 'Czechia')
```

--------------------------------

### IANA Timezone Identifier Examples

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/data-dictionary.md

Common IANA/tz database identifiers used in the timezone field.

```python
# Examples
'America/Los_Angeles'  # Pacific Time
'America/New_York'     # Eastern Time
'Europe/London'        # Greenwich Mean Time
'Europe/Paris'         # Central European Time
'Asia/Tokyo'           # Japan Standard Time
'UTC'                  # Coordinated Universal Time
```

--------------------------------

### Module Initialization Behavior

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Demonstrates the initial state of the module upon import and the impact of loading mappers.

```python
import geonamescache

# At this point:
# - geonamescache module is loaded
# - No data files have been read
# - Memory footprint is minimal
```

```python
from geonamescache.mappers import country

# At this point:
# - A module-level GeonamesCache instance is created
# - get_countries() is called to populate the dataset
# - Countries data is loaded into memory
```

--------------------------------

### Import Core GeonamesCache Class

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Initialize the main GeonamesCache instance to access geographic data methods.

```python
from geonamescache import GeonamesCache

gc = GeonamesCache()
countries = gc.get_countries()
```

--------------------------------

### Check current configuration

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Access the current population threshold setting.

```python
print(gc.min_city_population)  # Show current threshold
```

--------------------------------

### Inspect GeonamesCache instance configuration

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/configuration.md

Access instance configuration and verify cache state after initialization.

```python
import geonamescache

gc = geonamescache.GeonamesCache(min_city_population=1000)

# Access the configuration
print(gc.min_city_population)  # Output: 1000

# View cache state (None until data is loaded)
print(gc.countries)     # None until get_countries() is called
print(gc.cities)        # None until get_cities() is called
```

--------------------------------

### Import GeonamesCache Class

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Import the main cache class for accessing geospatial data.

```python
from geonamescache import GeonamesCache
```

--------------------------------

### Initialize GeonamesCache with different population thresholds

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/configuration.md

Configure the instance to load specific city datasets based on population size. Changing this value after initialization does not reload the cache.

```python
import geonamescache

# Default: includes only cities with population ≥ 15,000
gc = geonamescache.GeonamesCache()

# Includes smaller cities and towns with population ≥ 500
gc_detailed = geonamescache.GeonamesCache(min_city_population=500)

# Include cities with population ≥ 1,000
gc_medium = geonamescache.GeonamesCache(min_city_population=1000)

# Only major cities (same as default)
gc_major = geonamescache.GeonamesCache(min_city_population=15000)
```

--------------------------------

### Configure GeonamesCache instances

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/configuration.md

Common patterns for initializing GeonamesCache, including default settings, specific population thresholds, singleton patterns, and multiple instances.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
# Uses default: min_city_population=15000
```

```python
import geonamescache

gc = geonamescache.GeonamesCache(min_city_population=500)
# Includes all cities regardless of size
```

```python
# In your application initialization
import geonamescache

_gc = None

def get_geonames_cache():
    global _gc
    if _gc is None:
        _gc = geonamescache.GeonamesCache(min_city_population=1000)
    return _gc

# Throughout your application
gc = get_geonames_cache()
countries = gc.get_countries()
```

```python
import geonamescache

# For user-facing features requiring complete city data
full_gc = geonamescache.GeonamesCache(min_city_population=500)

# For internal queries needing only major cities
fast_gc = geonamescache.GeonamesCache(min_city_population=15000)
```

--------------------------------

### Initialize and Retrieve Country Data

Source: https://github.com/yaph/geonamescache/blob/master/README.md

Basic usage to initialize the cache and fetch country information.

```python
import geonamescache

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

--------------------------------

### GeonamesCache.__init__

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Initializes a new GeonamesCache instance, loading geospatial data from bundled JSON files based on the specified population threshold.

```APIDOC
## Constructor: GeonamesCache(min_city_population: int = 15000)

### Description
Initializes a GeonamesCache instance. The cache loads geospatial data from bundled JSON files. All data is loaded on-demand when getter methods are first called.

### Parameters
- **min_city_population** (int) - Optional (Default: 15000) - Minimum population threshold for cities dataset. Valid values: 500, 1000, 5000, 15000.
```

--------------------------------

### Implement Type Hints for IDE Support

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Import specific types from geonamescache.types to enable IDE autocompletion and static analysis.

```python
from geonamescache import GeonamesCache
from geonamescache.types import City, Country, Continent

def process_city(city: City) -> str:
    """Type hints enable IDE autocompletion."""
    return f"{city['name']}, {city['countrycode']}"

def get_capital(country: Country) -> str:
    return country['capital']

gc = GeonamesCache()
countries: dict[str, Country] = gc.get_countries()
cities: dict[str, City] = gc.get_cities()
continents: dict[str, Continent] = gc.get_continents()
```

--------------------------------

### Initialize GeonamesCache

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Instantiate the cache with an optional minimum city population threshold to filter the cities dataset.

```python
import geonamescache

# Create cache with default city population threshold
gc = geonamescache.GeonamesCache()

# Create cache with lower population threshold to include smaller cities
gc_detailed = geonamescache.GeonamesCache(min_city_population=500)
```

--------------------------------

### Create Custom City Indexes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Build custom dictionaries for frequent lookups by non-standard keys to avoid repeated iteration.

```python
cities_by_country = {}
for gid, city in cities.items():
    code = city['countrycode']
    if code not in cities_by_country:
        cities_by_country[code] = []
    cities_by_country[code].append((gid, city))
```

--------------------------------

### Create City Lookups by Country

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Manually index city data by country code to enable efficient lookups for specific regions.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

cities = gc.get_cities()

# Index cities by country code
cities_by_country = {}
for gid, city in cities.items():
    country_code = city['countrycode']
    if country_code not in cities_by_country:
        cities_by_country[country_code] = []
    cities_by_country[country_code].append((gid, city))

# Find all cities in Spain
spain_cities = cities_by_country.get('ES', [])
print(f"Found {len(spain_cities)} cities in Spain")
```

--------------------------------

### Configure population thresholds

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Set the minimum city population during GeonamesCache initialization.

```python
gc = GeonamesCache()                                # 15000+ (default)
gc = GeonamesCache(min_city_population=5000)       # 5000+
gc = GeonamesCache(min_city_population=1000)       # 1000+
gc = GeonamesCache(min_city_population=500)        # 500+
```

--------------------------------

### Import geonamescache types

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Import type aliases, literals, and TypedDict definitions for use in type hinting.

```python
from geonamescache.types import (
    City,
    CitySearchAttribute,
    Continent,
    ContinentCode,
    Country,
    ContinentAlternateName,
    CountryFields,
    CountryNumericFields,
    CountryStringFields,
    GeoNameIdStr,
    ISOStr,
    TimeZone,
    BBox,
    USCounty,
    USState,
    USStateCode,
    USStateName,
)
```

--------------------------------

### Initialize and Query Countries

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Access country data by ISO code after initializing the GeonamesCache instance.

```python
import geonamescache

# Initialize the cache
gc = geonamescache.GeonamesCache()

# Get all countries
countries = gc.get_countries()

# Access a specific country by ISO code
spain = countries['ES']
print(spain['name'])        # 'Spain'
print(spain['capital'])     # 'Madrid'
print(spain['population'])  # Population count
print(spain['iso3'])        # 'ESP'
print(spain['continentcode'])  # 'EU'
```

--------------------------------

### Initialize and Query Cities

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Access city data by GeoNames ID after initializing the GeonamesCache instance.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Get all cities
cities = gc.get_cities()

# Access a city by GeoNames ID
samobor = cities['3191316']
print(samobor['name'])           # 'Samobor'
print(samobor['countrycode'])    # 'HR'
print(samobor['latitude'])       # Latitude
print(samobor['longitude'])      # Longitude
print(samobor['population'])     # Population
print(samobor['timezone'])       # 'Europe/Zagreb'
```

--------------------------------

### Retrieve countries by ISO code

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Returns a dictionary of countries keyed by their 2-letter ISO 3166-1 code.

```python
import geonamescache

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

# Access Spain
spain = countries['ES']
print(spain['name'])  # 'Spain'
print(spain['iso3'])  # 'ESP'
print(spain['population'])  # Population
print(spain['capital'])  # 'Madrid'
print(spain['continentcode'])  # 'EU'
```

--------------------------------

### Access Package Metadata

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Metadata attributes available within the main package.

```python
__title__ = 'geonamescache'
__version__ = '3.0.2'
__author__ = 'Ramiro Gómez'
__license__ = 'MIT'
```

--------------------------------

### Reorganize Datasets with Custom Lookups

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Use get_dataset_by_key to index country or state data by specific attributes like ISO-3 or FIPS codes.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Reorganize countries by ISO-3 code
countries = gc.get_countries()
countries_by_iso3 = gc.get_dataset_by_key(countries, 'iso3')
print(countries_by_iso3['ESP']['name'])  # 'Spain'

# Reorganize US states by FIPS code
us_states = gc.get_us_states()
states_by_fips = gc.get_dataset_by_key(us_states, 'fips')
```

--------------------------------

### Parse language codes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/data-dictionary.md

Shows how to split the comma-separated languages string into a list of individual language codes.

```python
# Example: Spain's languages
languages_str = 'es-ES,ca,gl,eu,oc'
language_codes = languages_str.split(',')  # ['es-ES', 'ca', 'gl', 'eu', 'oc']
# es-ES = Spanish (Spain), ca = Catalan, gl = Galician, eu = Basque, oc = Occitan
```

--------------------------------

### Map Country Names to ISO Codes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Use the country mapper to convert country names or variants into ISO-3 codes.

```python
from geonamescache.mappers import country

# Create a name-to-ISO3 mapper
mapper = country(from_key='name', to_key='iso3')

# Map country names to ISO-3 codes
print(mapper('Spain'))          # 'ESP'
print(mapper('France'))         # 'FRA'
print(mapper('United States'))  # 'USA'

# Handles name variants automatically
print(mapper('USA'))            # 'USA' (mapped from variant)
print(mapper('Burma'))          # 'MMR' (mapped to Myanmar)
print(mapper('The Netherlands')) # 'NLD'
```

--------------------------------

### Search Cities with GeonamesCache

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Demonstrates various search configurations including case sensitivity, exact matching, and attribute-specific queries.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Search for 'Kiev' in alternate names (default, case-insensitive)
results = gc.search_cities('Kiev')
# Returns cities with 'Kiev' in their alternate names

# Case-sensitive search
results = gc.search_cities('Stoke-On-Trent', case_sensitive=True)
# Returns only exact case matches

# Exact match search
results = gc.search_cities('London', attribute='name', contains_search=False)
# Returns cities with exact name 'London'

# Search by country code
results = gc.search_cities('US', attribute='countrycode', contains_search=False)
# Returns all cities in the United States

# Search by timezone
results = gc.search_cities('UTC', attribute='timezone', case_sensitive=True)
# Returns cities in the UTC timezone
```

--------------------------------

### Import country name mappings

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Access the country name variant dictionary from the mappings module.

```python
from geonamescache.mappings import country_names
```

--------------------------------

### Import Type Aliases for Type Hints

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Access specific type aliases from the types module to improve code readability and static analysis.

```python
from geonamescache.types import (
    City,
    Country,
    USStateCode,
    ContinentCode,
)
from typing import Callable

def find_city_by_name(name: str, cities: dict[str, City]) -> City | None:
    for city in cities.values():
        if city['name'] == name:
            return city
    return None

def get_country_continent(country: Country) -> ContinentCode:
    return country['continentcode']
```

--------------------------------

### Retrieve cities by name using GeonamesCache

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Demonstrates searching for cities by name, handling both unique and non-unique results.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Look up a unique city name
samobor_list = gc.get_cities_by_name('Samobor')
# Returns: [{'3191316': {'name': 'Samobor', 'countrycode': 'HR', ...}}]

# Look up a common city name
madrid_list = gc.get_cities_by_name('Madrid')
# Returns multiple entries since Madrid appears in multiple countries
for city_dict in madrid_list:
    gid, city = list(city_dict.items())[0]
    print(f"{city['name']} ({city['countrycode']})")
```

--------------------------------

### Retrieve countries by name

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Returns a dictionary of countries keyed by their official name for alternative lookup.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
countries_by_name = gc.get_countries_by_names()

# Look up by name
spain = countries_by_name['Spain']
print(spain['iso'])  # 'ES'
print(spain['iso3'])  # 'ESP'
```

--------------------------------

### On-Demand Data Loading

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Illustrates how data is loaded lazily only when specific getter methods are invoked.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
# Data not loaded yet

continents = gc.get_continents()
# Continents data loaded on first call

continents2 = gc.get_continents()
# Cached result returned, no I/O

cities = gc.get_cities()
# Cities data loaded independently on first call
```

--------------------------------

### Implement Lazy Loading for Datasets

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Datasets are loaded into memory only upon the first access, and subsequent calls return the cached data.

```python
import geonamescache

# Cache initialization is fast (no data loaded yet)
gc = geonamescache.GeonamesCache()

# Data is loaded only when first accessed
countries = gc.get_countries()  # First call: loads data
countries2 = gc.get_countries()  # Second call: returns cached data

# Different datasets load independently
cities = gc.get_cities()  # Separate load
continents = gc.get_continents()  # Separate load
```

--------------------------------

### Handle missing items

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Use standard dictionary checks or safe access methods to prevent key errors.

```python
# Using 'in' operator
if 'ES' in countries:
    spain = countries['ES']

# Using get() for safe access
spain = countries.get('ES')
if spain:
    print(spain['name'])

# List operations
cities = gc.get_cities_by_name('Madrid')
if cities:
    print(f"Found {len(cities)} cities named Madrid")
```

--------------------------------

### Perform Basic City Searches

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Search for cities using alternate names or exact primary name matches.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Search for cities by alternate name (default)
results = gc.search_cities('Kiev')
for city in results:
    print(f"{city['name']} ({city['countrycode']})")

# Search by primary name (exact match)
results = gc.search_cities('London', attribute='name', contains_search=False)
for city in results:
    print(f"{city['name']} - {city['countrycode']}")
```

--------------------------------

### Configure Case-Sensitive Searches

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Toggle case sensitivity for city name searches using the case_sensitive parameter.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Case-insensitive (default) - finds 'Stoke-on-Trent'
results = gc.search_cities('Stoke-On-Trent', case_sensitive=False)
print(f"Case-insensitive: {len(results)} results")

# Case-sensitive - requires exact case
results = gc.search_cities('Stoke-On-Trent', case_sensitive=True)
print(f"Case-sensitive: {len(results)} results")
```

--------------------------------

### Create and use custom country mappings

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/mappings.md

Extend the library's read-only country_names mapping by merging it with a custom dictionary. This allows for flexible name normalization before passing the result to the standard country mapper.

```python
from geonamescache.mappings import country_names
from geonamescache.mappers import country

# Combine with custom mappings
custom_names = {
    **country_names,
    'Your Custom Name': 'Canonical Name',
}

# Use in your own mapping function
def custom_country_mapper(name, to_key='iso'):
    normalized = custom_names.get(name, name)
    mapper = country(from_key='name', to_key=to_key)
    return mapper(normalized)
```

--------------------------------

### Handle Missing Dictionary Keys

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Use dictionary .get() methods or membership checks to safely access country data.

```python
import geonamescache

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

# Use get() for safe access
spain = countries.get('ES')
if spain:
    print(spain['name'])
else:
    print("Country not found")

# Or check membership first
if 'XX' in countries:
    print(countries['XX']['name'])
else:
    print("Invalid country code")
```

--------------------------------

### Create Custom Lookups in Python

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Transform existing collections into custom dictionaries or filtered lists for efficient data retrieval.

```python
# Reorganize countries by ISO-3
countries_by_iso3 = {c['iso3']: c for c in countries.values()}

# Find all cities in a country
cities_in_us = [c for c in cities.values() if c['countrycode'] == 'US']

# Index counties by FIPS
counties_by_fips = {c['fips']: c for c in counties}
```

--------------------------------

### Import GeonamesCache Types

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Import specific type definitions for use in type hinting functions.

```python
from geonamescache import (
    GeonamesCache,
    City,
    Continent,
    Country,
    ContinentCode,
    USState,
    USCounty,
    USStateCode,
)

def process_city(city: City) -> None:
    print(city['name'])

def process_country(country: Country) -> None:
    print(f"{country['name']} ({country['iso']})")
```

--------------------------------

### Define GeonamesCache constructor

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/configuration.md

The constructor accepts an optional min_city_population parameter to filter city datasets.

```python
class GeonamesCache:
    def __init__(self, min_city_population: int = 15000):
        self.min_city_population = min_city_population
```

--------------------------------

### Execute Multiple Criteria Searches

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Combine search results programmatically to filter cities by multiple criteria.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Find cities matching multiple criteria by combining searches
us_cities = gc.search_cities('US', attribute='countrycode', contains_search=False)
london_in_us = [c for c in us_cities if 'London' in c['name']]

for city in london_in_us:
    print(f"{city['name']}, {city['admin1code']}")
```

--------------------------------

### Map ISO Codes to Country Attributes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Retrieve specific country attributes like capital, currency, or continent using ISO codes.

```python
from geonamescache.mappers import country

# ISO to capital
iso_to_capital = country(from_key='iso', to_key='capital')
print(iso_to_capital('FR'))  # 'Paris'
print(iso_to_capital('ES'))  # 'Madrid'

# ISO to currency
iso_to_currency = country(from_key='iso', to_key='currencycode')
print(iso_to_currency('US'))  # 'USD'
print(iso_to_currency('ES'))  # 'EUR'

# ISO to continent
iso_to_continent = country(from_key='iso', to_key='continentcode')
print(iso_to_continent('AU'))  # 'OC' (Oceania)
print(iso_to_continent('JP'))  # 'AS' (Asia)
```

--------------------------------

### Perform Basic Text Search

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Search for cities using substring matching with options for case sensitivity and exact matching.

```python
# Case-insensitive substring search (default)
results = gc.search_cities('London')

# Case-sensitive search
results = gc.search_cities('London', case_sensitive=True)

# Exact match
results = gc.search_cities('London', contains_search=False)
```

--------------------------------

### Handle Optional Fields

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Check for the existence of optional keys like 'cc2' before accessing them in continent data.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
continents = gc.get_continents()

# Some fields are optional (cc2)
africa = continents['AF']
cc2 = africa.get('cc2')  # May be missing
if cc2:
    print(f"Alternative code: {cc2}")
```

--------------------------------

### Retrieve US counties using GeonamesCache

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Shows how to fetch all US counties and perform lookups by FIPS code or filter by state.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
counties = gc.get_us_counties()

# Create a lookup by FIPS code
counties_by_fips = {c['fips']: c for c in counties}

# Access Los Angeles County
la_county = counties_by_fips['06037']
print(la_county['name'])  # 'Los Angeles County'
print(la_county['state'])  # 'CA'

# Find all counties in California
ca_counties = [c for c in counties if c['state'] == 'CA']
```

--------------------------------

### Retrieve US states by name

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Returns a dictionary of US states keyed by their official name for easier lookup.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
states_by_name = gc.get_us_states_by_names()

# Look up by name
california = states_by_name['California']
print(california['code'])  # 'CA'
print(california['fips'])  # FIPS number
```

--------------------------------

### Seed Databases with Geonames Data

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Iterate through country and city datasets to populate database tables.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Seed countries table
countries = gc.get_countries()
for iso_code, country_data in countries.items():
    db.insert('countries', {
        'iso': country_data['iso'],
        'iso3': country_data['iso3'],
        'name': country_data['name'],
        'population': country_data['population'],
        'capital': country_data['capital']
    })

# Seed cities table
cities = gc.get_cities()
for gid, city_data in cities.items():
    db.insert('cities', {
        'geonameid': gid,
        'name': city_data['name'],
        'countrycode': city_data['countrycode'],
        'latitude': city_data['latitude'],
        'longitude': city_data['longitude'],
        'population': city_data['population']
    })
```

--------------------------------

### Optimize Memory Usage

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Reduce memory footprint by setting a minimum population threshold for cities or by only accessing required datasets.

```python
import geonamescache

# Use higher population threshold to reduce memory usage
# (only loads major cities ~43,000 instead of ~165,000)
gc = geonamescache.GeonamesCache(min_city_population=15000)

# Only load datasets you need
countries = gc.get_countries()  # Load only countries

# Skip cities dataset if not needed
# (gc.get_cities() is never called)
```

--------------------------------

### Access and use country_names mapping

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/mappings.md

Demonstrates direct access to the mapping dictionary and its automatic application within the country mapper.

```python
from geonamescache.mappers import country
from geonamescache.mappings import country_names

# Direct mapping access
canonical_name = country_names.get('USA')
# Returns 'United States'

# Automatic application in country mapper
mapper = country(from_key='name', to_key='iso')
iso = mapper('USA')  # Automatically applies mapping, returns 'US'

# Checking if a variant exists
if 'Czech Republic' in country_names:
    print(f"Czech Republic maps to {country_names['Czech Republic']}")
    # Prints: Czech Republic maps to Czechia
```

--------------------------------

### Sort countries by population

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Order all countries by their population attribute.

```python
sorted_countries = sorted(countries.values(),
                         key=lambda x: x['population'],
                         reverse=True)
```

--------------------------------

### Perform Batch Operations with Mappers

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Use the mapper utility to transform lists of identifiers, such as converting country names to ISO-3 codes.

```python
import geonamescache
from geonamescache.mappers import country

gc = geonamescache.GeonamesCache()
mapper = country(from_key='name', to_key='iso3')

# Process a list of country names
country_names = ['Spain', 'France', 'Germany', 'Italy', 'USA']

results = []
for name in country_names:
    iso3 = mapper(name)
    if iso3:
        results.append((name, iso3))

for name, iso3 in results:
    print(f"{name}: {iso3}")
```

--------------------------------

### Retrieve US states

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Returns a dictionary of US states and territories keyed by their 2-letter state code.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
us_states = gc.get_us_states()

# Access California
ca = us_states['CA']
print(ca['name'])  # 'California'
print(ca['fips'])  # FIPS code
print(ca['geonameid'])  # GeoNames ID
```

--------------------------------

### Retrieve US states by name

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Access US state data indexed by name for direct lookups.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Get states indexed by name
states_by_name = gc.get_us_states_by_names()

# Look up by name
texas = states_by_name['Texas']
print(f"Texas code: {texas['code']}, FIPS: {texas['fips']}")
```

--------------------------------

### Access Country Name Mappings

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Use the mappings module to resolve canonical names from variant country names.

```python
from geonamescache.mappings import country_names

# Check if a country name has a variant mapping
if 'USA' in country_names:
    canonical = country_names['USA']
    print(f"USA maps to {canonical}")
```

--------------------------------

### Import and Use Mappers

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Utilize mapper functions to convert between different geographic naming conventions or codes.

```python
from geonamescache.mappers import country

name_to_iso3 = country(from_key='name', to_key='iso3')
iso3 = name_to_iso3('Spain')
```

--------------------------------

### Handle Conditional Imports for Typing

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Use this pattern to maintain compatibility with Python versions older than 3.11 by conditionally importing typing features.

```python
import sys

if sys.version_info >= (3, 11):
    from typing import NotRequired, TypedDict
else:
    from typing_extensions import NotRequired, TypedDict
```

--------------------------------

### Import Country Mapper

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/module-structure.md

Import the function used to create country attribute mapper functions.

```python
from geonamescache.mappers import country
```

--------------------------------

### country(from_key='name', to_key='iso')

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/mappers.md

Creates a bidirectional mapper function that converts a country attribute from a source key to a target key. When using 'name' as the source key, it automatically normalizes common country name variants.

```APIDOC
## Function: country(from_key: str = "name", to_key: CountryFields = "iso")

### Description
Creates a mapper function that accepts a single string argument and returns the corresponding country field value. The mapper handles normalization for country names when `from_key` is set to "name".

### Parameters
- **from_key** (str) - Optional - Country attribute to use for input lookup (default: "name").
- **to_key** (CountryFields) - Optional - Country attribute to return (default: "iso").

### Return Type
- **Callable[[str], Any]** - A function that returns the target field value or `None` if no match is found.

### Usage Example
```python
from geonamescache.mappers import country

# Create a name-to-ISO3 mapper
mapper = country(from_key='name', to_key='iso3')
iso3 = mapper('Spain')  # Returns 'ESP'
iso3 = mapper('Burma')  # Returns 'MMR' (applies name mapping)
```
```

--------------------------------

### Handle mapper errors

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Check for None results when using a mapper to look up values.

```python
mapper = country(from_key='name', to_key='iso3')
iso3 = mapper('NonexistentCountry')
if iso3 is None:
    print("Country not found")
else:
    print(f"ISO-3: {iso3}")
```

--------------------------------

### Define BBox TypedDict

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/types.md

Defines geographic boundaries using latitude and longitude coordinates.

```python
class BBox(TypedDict):
    accuracyLevel: int      # Accuracy level indicator
    east: float             # Eastern boundary longitude
    north: float            # Northern boundary latitude
    south: float            # Southern boundary latitude
    west: float             # Western boundary longitude
```

--------------------------------

### Cache GeonamesCache Instance

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Instantiate GeonamesCache once and reuse the object throughout the application to improve performance.

```python
gc = GeonamesCache()  # Create once
# Use gc throughout app
```

--------------------------------

### Integrate with FastAPI

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Expose geonamescache data through a REST API endpoint with error handling for missing country names.

```python
from fastapi import FastAPI
import geonamescache
from geonamescache.mappers import country

app = FastAPI()
gc = geonamescache.GeonamesCache(min_city_population=1000)

@app.get("/countries/{country_name}")
def get_country_info(country_name: str):
    countries = gc.get_countries()
    countries_by_name = gc.get_dataset_by_key(countries, 'name')
    
    country = countries_by_name.get(country_name)
    if not country:
        return {"error": "Country not found"}
    
    return {
        "name": country['name'],
        "iso": country['iso'],
        "iso3": country['iso3'],
        "capital": country['capital'],
        "population": country['population']
    }
```

--------------------------------

### Mapper Functions

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/README.md

Utility function for mapping country data between different keys.

```python
country(from_key='name', to_key='iso') → Callable[[str], str|int|ContinentCode]
```

--------------------------------

### Handle Not Found Results with Mappers

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Check for None return values when using country mappers to identify missing data.

```python
import geonamescache
from geonamescache.mappers import country

gc = geonamescache.GeonamesCache()
mapper = country(from_key='name', to_key='iso3')

# Mapper returns None if not found
country_name = 'NonexistentCountry'
iso3 = mapper(country_name)

if iso3 is None:
    print(f"Country '{country_name}' not found")
else:
    print(f"ISO3 code: {iso3}")
```

--------------------------------

### Process neighbor country codes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/data-dictionary.md

Demonstrates splitting the comma-separated neighbors string and looking up country names using the geonamescache instance.

```python
# Example: Spain's neighbors
neighbors_str = 'PT,FR,AD,GI,MA'
neighbor_codes = neighbors_str.split(',')  # ['PT', 'FR', 'AD', 'GI', 'MA']

# Convert to country names
countries = gc.get_countries()
for code in neighbor_codes:
    if code in countries:
        print(countries[code]['name'])
```

--------------------------------

### get_countries()

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/data-dictionary.md

Retrieves a dictionary of country data where keys are ISO 3166-1 alpha-2 codes and values are objects containing country details.

```APIDOC
## get_countries()

### Description
Returns a dictionary containing comprehensive data for countries, indexed by their ISO 3166-1 alpha-2 code.

### Response Fields
- **areakm2** (int) - Land area in square kilometers
- **capital** (str) - Capital city name
- **continentcode** (ContinentCode) - Continent code
- **currencycode** (str) - ISO 4217 currency code
- **currencyname** (str) - Official currency name
- **iso** (str) - ISO 3166-1 alpha-2 code
- **isonumeric** (int) - ISO 3166-1 numeric code
- **iso3** (str) - ISO 3166-1 alpha-3 code
- **fips** (str) - FIPS country code
- **geonameid** (int) - Unique GeoNames identifier
- **languages** (str) - Comma-separated language codes
- **name** (str) - English country name
- **neighbours** (str) - Comma-separated neighbor country codes
- **phone** (str) - International dialing code
- **population** (int) - Total population estimate
- **postalcoderegex** (str) - Regex for postal code validation
- **tld** (str) - Top-level domain
```

--------------------------------

### Filter cities by state and country

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Retrieve cities matching specific administrative codes within a country.

```python
state_codes = ['CA', 'TX', 'FL']
cities_in_states = [c for c in cities.values() 
                    if c['admin1code'] in state_codes and 
                       c['countrycode'] == 'US']
```

--------------------------------

### Mapper Functions

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/README.md

Utility functions for mapping geographical data keys.

```APIDOC
## country(from_key='name', to_key='iso')
Returns a callable that maps country identifiers between different formats.
```

--------------------------------

### Map Country Data Attributes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Use the country mapper to transform between different country attributes like names, ISO codes, capitals, and currencies. Returns None if the input key is not found.

```python
from geonamescache.mappers import country

# Create a mapper: mapper = country(from_key=X, to_key=Y)

# Common mappers
mapper = country(from_key='name', to_key='iso')        # Name → ISO-2
mapper = country(from_key='name', to_key='iso3')       # Name → ISO-3
mapper = country(from_key='iso', to_key='capital')     # Code → Capital
mapper = country(from_key='iso', to_key='currencycode') # Code → Currency

# Returns None if not found
iso = mapper('Spain')  # 'ES'
iso = mapper('Invalid')  # None
```

--------------------------------

### Retrieve cities by GeoNames ID

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Returns a dictionary of cities keyed by their GeoNames ID string, filtered by the minimum population threshold set during initialization.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
cities = gc.get_cities()

# Access a city by GeoNames ID
city = cities['3191316']  # Samobor
print(city['name'])  # 'Samobor'
print(city['countrycode'])  # 'HR'
print(city['latitude'])  # Latitude coordinate
print(city['longitude'])  # Longitude coordinate
print(city['population'])  # Population
```

--------------------------------

### gc.search_cities(name, attribute='name', case_sensitive=False, contains_search=True)

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Searches for cities based on a provided query string. The search can be filtered by specific attributes and configured for case sensitivity or exact matching.

```APIDOC
## Method: gc.search_cities

### Description
Searches for cities within the cache. By default, it performs a case-insensitive substring search on city names.

### Parameters
- **name** (string) - Required - The search query string.
- **attribute** (string) - Optional - The attribute to search against (e.g., 'name', 'countrycode', 'admin1code', 'timezone'). Defaults to 'name'.
- **case_sensitive** (boolean) - Optional - Whether the search should be case-sensitive. Defaults to False.
- **contains_search** (boolean) - Optional - Whether to perform a substring search. If False, performs an exact match. Defaults to True.
```

--------------------------------

### Validate Country Names

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Use country mappers to create validation functions for verifying country names against ISO codes.

```python
import geonamescache
from geonamescache.mappers import country

gc = geonamescache.GeonamesCache()
country_mapper = country(from_key='name', to_key='iso')

def validate_country_name(name: str) -> bool:
    """Check if a name maps to a valid country."""
    return country_mapper(name) is not None

def get_country_iso(name: str) -> str | None:
    """Get ISO code for a country name, or None if invalid."""
    return country_mapper(name)

# Use in validation
if validate_country_name('Spain'):
    print("Valid country")
else:
    print("Invalid country")
```

--------------------------------

### Overload signatures for country mapper

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/mappers.md

Type-safe signatures for the country mapper based on the return type of the target field.

```python
def country(from_key: str = "name", *, to_key: CountryNumericFields) -> Callable[[str], int]: ...
```

```python
def country(from_key: str = "name", to_key: CountryStringFields = "iso") -> Callable[[str], str]: ...
```

```python
def country(from_key: str = "name", *, to_key: Literal["continentcode"]) -> Callable[[str], ContinentCode]: ...
```

--------------------------------

### Type Aliases

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/README.md

List of type aliases used throughout the library.

```python
GeoNameIdStr, ISOStr, ContinentCode, USStateCode, USStateName,
CitySearchAttribute, CountryFields, CountryNumericFields, CountryStringFields
```

--------------------------------

### Define ISOStr

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/types.md

Represents a 2-letter ISO 3166-1 country code as a string.

```python
ISOStr = str
```

--------------------------------

### Iterate Collections in Python

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Loop through dictionary items or list collections to process geographic data.

```python
# All items
for code, country in countries.items():
    print(f"{code}: {country['name']}")

for gid, city in cities.items():
    print(f"{city['name']} ({city['countrycode']})")

for county in counties:
    print(f"{county['name']} ({county['state']})")
```

--------------------------------

### Data Types

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/README.md

List of TypedDict classes used for data representation.

```python
City, Continent, Country, USState, USCounty, TimeZone, BBox, ContinentAlternateName
```

--------------------------------

### Retrieve and iterate US states

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Access US state data by code or iterate through the full dictionary of states.

```python
import geonamescache

gc = geonamescache.GeonamesCache()

# Get all US states
states = gc.get_us_states()

# Iterate over all states
for code, state in states.items():
    print(f"{state['name']} ({code}): geonameid={state['geonameid']}")

# Access a specific state
california = states['CA']
print(f"State: {california['name']}, FIPS: {california['fips']}")
```

--------------------------------

### Retrieve Continents Data

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Fetch a dictionary of continents keyed by ISO code and access specific continent details.

```python
import geonamescache

gc = geonamescache.GeonamesCache()
continents = gc.get_continents()

# Access Africa
africa = continents['AF']
print(africa['name'])  # 'Africa'
print(africa['population'])  # Population count
print(africa['bbox'])  # Bounding box coordinates
```

--------------------------------

### Map Country Properties

Source: https://github.com/yaph/geonamescache/blob/master/README.md

Use the mappers module to convert between different country property keys.

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

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

--------------------------------

### get_us_states_by_names

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/geonamescache-main.md

Returns a dictionary of US states keyed by their official name, allowing for name-based lookups.

```APIDOC
## get_us_states_by_names

### Description
Returns the US states dictionary reorganized with state names as keys instead of state codes. Provides name-based lookup for US state records.

### Signature
`def get_us_states_by_names(self) -> dict[USStateName, USState]`

### Returns
- **dict[USStateName, USState]** - A dictionary of US states keyed by their official name.

### Example
```python
import geonamescache

gc = geonamescache.GeonamesCache()
states_by_name = gc.get_us_states_by_names()

# Look up by name
california = states_by_name['California']
print(california['code'])  # 'CA'
print(california['fips'])  # FIPS number
```
```

--------------------------------

### GeonamesCache Lookup Methods

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Methods for retrieving data reorganized by specific keys or names.

```APIDOC
## Data Lookup Methods

### get_countries_by_names()
Returns a dictionary of countries keyed by country name.

### get_us_states_by_names()
Returns a dictionary of US states keyed by state name.

### get_cities_by_name(name)
Returns a list of dictionaries containing city data for cities matching the provided name.
```

--------------------------------

### Access Single Records in Python

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/quick-reference.md

Retrieve specific records from continents, countries, states, or cities using their respective keys or IDs.

```python
# Continent
africa = continents['AF']

# Country
spain = countries['ES']

# US State
california = us_states['CA']

# City (by GeoNames ID)
city = cities['3191316']

# Country by name
spain = countries_by_names['Spain']

# State by name
california = states_by_names['California']
```

--------------------------------

### Define country_names type

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/mappings.md

Type definition for the country_names dictionary.

```python
country_names: dict[str, str]
```

--------------------------------

### Retrieve Numeric Country Attributes

Source: https://github.com/yaph/geonamescache/blob/master/_autodocs/usage-patterns.md

Extract population, area, or numeric ISO codes using the country mapper.

```python
from geonamescache.mappers import country

# Name to population
name_to_pop = country(from_key='name', to_key='population')
us_pop = name_to_pop('United States')
print(f"US Population: {us_pop:,}")

# Name to area
name_to_area = country(from_key='name', to_key='areakm2')
france_area = name_to_area('France')
print(f"France Area: {france_area:,} km²")

# Name to numeric ISO code
name_to_iso_num = country(from_key='name', to_key='isonumeric')
iso_num = name_to_iso_num('Spain')
print(f"Spain ISO Numeric: {iso_num}")
```
Tokens:
Raw