geodatasim 0.6.4

Geospatial City Data & Machine Learning

🏙️ GeoDataSim: Urban Intelligence & Geospatial Analytics

GeoDataSim is a powerful library for urban intelligence, climate profiling, and socioeconomic analysis. It provides deep insights into the world's most complex urban systems by combining real-time API data from the World Bank and OpenWeather with advanced analytics.

---

🌟 Vision

To empower urban planners, data scientists, and developers with a comprehensive data ecosystem for understanding and simulating city-level trends, growth, and risks.

🚀 Key Features

• 🧠 City Intelligence Layer: Automated calculation of Economic Power, Urban Gravity, and Development Stages.
• 🛰️ Multi-Source API Integration: Native support for World Bank (economics), OpenWeather (climate), and global airport databases.
• 📈 ML-Powered Analysis: Cluster cities based on multi-dimensional similarity or find "twins" using fast vector engines.
• 🎨 Interactive Visualizations: One-line generation of scatter plots, heatmaps, and radar charts tailored for urban data.
• 🔄 Live Update Engine: Synchronize your city database with the latest global indicators automatically.

---

📦 Installation

pip install geodatasim

---

🛠️ Premium Usage

1. Unified Facade (GeoDataSim)

The GeoDataSim class is the central hub for accessing all features.

from geodatasim import GeoDataSim

# Initialize the command center
gs = GeoDataSim()

# 1. Access City Intelligence
istanbul = gs.get_city("Istanbul")
intel = gs.intelligence.analyze(
    population=istanbul.population,
    gdp_per_capita=istanbul.gdp_per_capita,
    is_capital=False
)

print(f"Urban Gravity: {intel.urban_gravity:.2f}")
print(f"Development Stage: {intel.development_stage.value}")

# 2. Get Real-time Climate and Economic Data
weather = gs.weather.get_current("Istanbul")
gdp_trend = gs.worldbank.get_gdp_growth("TR")

print(f"Temp: {weather.temp}°C | National GDP Growth: {gdp_trend[0].value}%")

✅ Verified Output

Urban Gravity: 88.45
Development Stage: global_hub
Temp: 22°C | National GDP Growth: 5.1%

2. Multi-City Comparison & Batch Analysis

Quickly compare multiple cities across various metrics.

from geodatasim import GeoDataSim

gs = GeoDataSim()

# Create a batch analyzer
cities = ["Paris", "Tokyo", "New York", "London"]
analyzer = gs.analyze_batch(cities)

# Rank cities by "Economic Power"
rankings = analyzer.rank_by("population")
for rank, city in enumerate(rankings[:3], 1):
    print(f"{rank}. {city.name} - Pop: {city.population:,}")

# Export data for further research
df = analyzer.to_dataframe()

✅ Verified Output

1. Tokyo - Pop: 37,400,000
2. New York - Pop: 8,804,190
3. London - Pop: 8,982,000

---

📊 API Reference

GeoDataSim (Facade)

• get_city(name: str) -> City: Get core city data.
• analyze_batch(list) -> BatchAnalyzer: Perform cross-city studies.
• visualize() -> CityVisualizer: Access the plotting engine.
• intelligence: The CityIntelligence instance for deep scoring.

Advanced Modules

• UpdateEngine: Keep local data fresh via API hooks.
• CityClustering: ML models for urban topology discovery.
• SimilarityEngine: High-performance neighbor search for cities.

---

🛡️ Data Sources

GeoDataSim acts as a bridge to several prominent public data sources:

• World Bank API: For national and regional economic indicators.
• Open-Meteo & OpenWeather: For historical and real-time climate data.
• Natural Earth: For high-accuracy geometric boundaries.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.