AigeoDB
A Python package for working with world cities, countries, regions database. This package provides easy access to a comprehensive database of world locations.
Features
- Easy-to-use interface for querying geographical data
- Built-in database downloader and updater
- Support for searching cities, countries, and regions
- Geolocation features (nearby cities search)
- SQLite database with Peewee ORM
- Django integration with custom model fields
- Robust date handling and data validation
- Snake case field names with backward compatibility
Installation
Basic installation:
pip install aigeodb
Core Usage
Basic Example
from aigeodb import DatabaseManager
# Initialize the database manager
db = DatabaseManager()
# Search for cities
cities = db.search_cities("Moscow", limit=5)
for city in cities:
print(f"{city.name}, {city.country_code}")
print(f"Location: ({city.latitude}, {city.longitude})")
print(f"State: {city.state_code}")
# Get country information
country = db.get_country_info("US")
print(f"{country['name']} ({country['iso2']})")
print(f"Capital: {country['capital']}")
print(f"Currency: {country['currency']} ({country['currency_symbol']})")
# Find nearby cities
cities = db.get_nearby_cities(
latitude=40.7128,
longitude=-74.0060,
radius_km=100,
limit=10
)
for city in cities:
print(f"{city.name}, {city.state_code} ({city.latitude}, {city.longitude})")
Data Models
All models use snake_case field names with aliases for backward compatibility:
# City model fields
city = cities[0]
print(f"ID: {city.id}")
print(f"Name: {city.name}")
print(f"State ID: {city.state_id}") # aliased as 'state' in database
print(f"State Code: {city.state_code}")
print(f"Country ID: {city.country_id}") # aliased as 'country' in database
print(f"Country Code: {city.country_code}")
print(f"Location: ({city.latitude}, {city.longitude})")
print(f"Created: {city.created_at}")
print(f"Updated: {city.updated_at}")
print(f"Active: {city.flag}")
print(f"Wiki Data: {city.wiki_data_id}") # aliased as 'wikiDataId' in database
# Country model fields
country = db.get_country_by_code("US")
print(f"Basic Info: {country.name} ({country.iso2}, {country.iso3})")
print(f"Codes: {country.numeric_code}, {country.phonecode}")
print(f"Location: {country.region}, {country.subregion}")
print(f"Currency: {country.currency} ({country.currency_symbol})")
print(f"Emoji: {country.emoji} ({country.emoji_u})") # emoji_u aliased as 'emojiU'
API Reference
# DatabaseManager methods
db = DatabaseManager()
# Search cities by name
cities = db.search_cities("Moscow", limit=5)
# Get country information
country = db.get_country_info("US")
# Calculate distance between two points
new_york = (40.7128, -74.0060) # (latitude, longitude)
london = (51.5074, -0.1278)
distance = db.calculate_distance(new_york, london)
print(f"Distance between cities: {distance:.1f}km")
# Find nearby cities
cities = db.get_nearby_cities(
latitude=40.7128,
longitude=-74.0060,
radius_km=100,
limit=10
)
# Get cities by country
cities = db.get_cities_by_country("US")
# Get states/regions by country
states = db.get_states_by_country("US")
# Get database statistics
stats = db.get_statistics()
Date Handling
The package handles dates robustly:
- Invalid dates ('0000-00-00 00:00:00') are automatically converted to
None - All date fields (
created_at,updated_at) are optional - Dates are stored in UTC format
- Dates are returned as Python
datetimeobjects
Example:
city = db.get_city_by_id(1)
if city.created_at:
print(f"Created: {city.created_at.strftime('%Y-%m-%d %H:%M:%S')}")
if city.updated_at:
print(f"Last Updated: {city.updated_at.strftime('%Y-%m-%d %H:%M:%S')}")
Distance Calculation
The package uses geopy for precise distance calculations using the geodesic formula. Coordinates are passed as tuples of (latitude, longitude).
Example distances:
# Some major city coordinates
new_york = (40.7128, -74.0060)
london = (51.5074, -0.1278)
paris = (48.8566, 2.3522)
tokyo = (35.6762, 139.6503)
seoul = (37.5665, 126.9780)
# Calculate distances
print(f"New York to London: {db.calculate_distance(new_york, london):.1f}km") # ~5,570km
print(f"Paris to Tokyo: {db.calculate_distance(paris, tokyo):.1f}km") # ~9,713km
print(f"Tokyo to Seoul: {db.calculate_distance(tokyo, seoul):.1f}km") # ~1,160km
Database Content
The package includes:
- Countries (250 records)
- Regions (6 records)
- Subregions (22 records)
- States/Regions/Municipalities (5,038 records)
- Cities/Towns/Districts (151,072 records)
Django Integration
AigeoDB provides Django model fields with Select2-powered autocomplete support for cities and countries. The integration includes custom widgets with dark mode support and AJAX search functionality.
Setup
- Add to INSTALLED_APPS:
INSTALLED_APPS = [
...
'aigeodb.django',
]
- Add URLs to your project's urls.py:
from django.urls import path, include
urlpatterns = [
...
path('aigeodb/', include('aigeodb.django.urls')),
]
- Make sure you have static files configured:
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'
STATICFILES_DIRS = [
BASE_DIR / 'static',
]
- Run collectstatic:
python manage.py collectstatic
Using Fields
from django.db import models
from aigeodb.django import CityField, CountryField
class Location(models.Model):
city = CityField()
country = CountryField()
# Fields can be optional
departure_city = CityField(null=True, blank=True)
def __str__(self):
return f"{self.city.name}, {self.country.name}"
Admin Integration
The fields work automatically in Django admin with Select2 widgets:
from django.contrib import admin
from aigeodb.django import AutocompleteFieldsMixin
@admin.register(Location)
class LocationAdmin(AutocompleteFieldsMixin, admin.ModelAdmin):
list_display = ('city', 'country')
search_fields = ('city__name', 'country__name')
Features
- Built-in Select2 integration with AJAX search
- Automatic dark/light theme support
- Efficient data loading with caching
- Built-in data validation
- Responsive design
- Support for Django admin inlines
- Thread-safe database access
Widget Customization
The fields use custom Select2 widgets that can be customized:
from django.db import models
from aigeodb.django import CityField, CountryField
class Location(models.Model):
city = CityField(
widget_attrs={
'data-placeholder': 'Search for a city...',
'data-minimum-input-length': '3',
'class': 'custom-select'
}
)
country = CountryField(
widget_attrs={
'data-placeholder': 'Select a country',
'style': 'width: 100%'
}
)
API Endpoints
The package provides two AJAX endpoints:
-
/aigeodb/search-cities/- Parameters:
term: Search query (min 2 characters)page: Page number for pagination
- Returns:
{ "results": [ { "id": "123", "text": "New York, United States" } ], "pagination": { "more": false } }
- Parameters:
-
/aigeodb/search-countries/- Parameters:
term: Search query (min 2 characters)page: Page number for pagination
- Returns:
{ "results": [ { "id": "US", "text": "United States" } ], "pagination": { "more": false } }
- Parameters:
Static Files
The package includes:
aigeodb/js/autocomplete-init.js- Select2 initializationaigeodb/css/autocomplete-theme.css- Theme styles with dark mode
These files are automatically included when using AutocompleteFieldsMixin.
About
Developed by Unrealos Inc. - We create innovative SaaS and PaaS solutions powered by AI for business. Our expertise includes:
- AI-powered business solutions
- SaaS platforms
- PaaS infrastructure
- Custom enterprise software
License
MIT License - see the LICENSE file for details.
Credits
- Data source: countries-states-cities-database
- Developed by Unrealos Inc.
Coordinate-Based Lookups
The package provides methods to find cities and countries by coordinates:
# Get city by coordinates
city = db.get_city_by_coordinates(
latitude=40.7128,
longitude=-74.0060
)
if city:
print(f"Nearest city: {city.name}, {city.country_code}")
# Get country by coordinates
country = db.get_country_by_coordinates(
latitude=40.7128,
longitude=-74.0060
)
if country:
print(f"Country at location: {country.name} ({country.iso2})")
Distance Calculation
The package uses geopy for precise distance calculations using the geodesic formula. Coordinates are passed as tuples of (latitude, longitude).
Example distances:
# Some major city coordinates
new_york = (40.7128, -74.0060)
london = (51.5074, -0.1278)
paris = (48.8566, 2.3522)
tokyo = (35.6762, 139.6503)
seoul = (37.5665, 126.9780)
# Calculate distances
print(f"New York to London: {db.calculate_distance(new_york, london):.1f}km") # ~5,570km
print(f"Paris to Tokyo: {db.calculate_distance(paris, tokyo):.1f}km") # ~9,713km
print(f"Tokyo to Seoul: {db.calculate_distance(tokyo, seoul):.1f}km") # ~1,160km
Metadata
Release files for aigeodb 0.2.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aigeodb-0.2.6.tar.gz | 13.5 MB | Without provenance | Details for aigeodb-0.2.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aigeodb-0.2.6-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details for aigeodb-0.2.6-py2.py3-none-any.whl |
Total release size: 27.2 MB
Release files / aigeodb-0.2.6.tar.gz
| Download URL | aigeodb-0.2.6.tar.gz |
|---|---|
| Size | 13.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
11db5677a0eaed5565b09f9f6853b62ab76a6d5b252d840a6e4978626e326702
|
|
BLAKE2b-256 checksum How to use checksums |
6646ff83128ed9b44d7fae12c701b4c01f7cc0ae55122d6616f2dae3d1f3d94a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.2
|
Release files / aigeodb-0.2.6-py2.py3-none-any.whl
| Download URL | aigeodb-0.2.6-py2.py3-none-any.whl |
|---|---|
| Size | 13.7 MB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
c46c0d7bc0eec448518640012793ecdfad8fa540b4c079bc2c7a2b3aad83f1e9
|
|
BLAKE2b-256 checksum How to use checksums |
b71fd61516f8e84ad7e366c9837b0236debe0ef6a62a241c6323254fddd8df8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.2
|
Security for aigeodb 0.2.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.