geodatasim 0.6.4
Geospatial City Data & Machine Learning
Requires Python: >=3.9

# 🏙️ GeoDataSim: Urban Intelligence & Geospatial Analytics

[![PyPI version](https://img.shields.io/pypi/v/geodatasim.svg)](https://pypi.org/project/geodatasim/)
[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)

**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

```bash
pip install geodatasim
```

---

## 🛠️ Premium Usage

### 1. Unified Facade (GeoDataSim)
The `GeoDataSim` class is the central hub for accessing all features.

```python
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
```text
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.

```python
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
```text
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.