Metadata-Version: 2.4
Name: django-worldbank
Version: 0.1.0
Summary: Django application to import and manage World Bank Open Data indicators
Author-email: Arthur Hanson <worldnomad@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/arthanson/django-worldbank
Project-URL: Documentation, https://github.com/arthanson/django-worldbank#readme
Project-URL: Repository, https://github.com/arthanson/django-worldbank
Project-URL: Issues, https://github.com/arthanson/django-worldbank/issues
Keywords: django,worldbank,indicators,development,data,economics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-django; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: responses; extra == "test"
Dynamic: license-file

# django-worldbank

A Django application to download and import data from the [World Bank Open Data](https://data.worldbank.org/) API.

## Features

- Import countries, indicators, and time-series data from World Bank API
- 12 organized categories: Demographics, Tourism, Economy, Health, Education, and more
- Configurable default indicators for travel context
- Category-based import for selective data loading
- Incremental updates with change detection
- Django admin integration

## Requirements

- Python 3.10+
- Django 4.2+
- requests

## Installation

```bash
pip install django-worldbank
```

Add to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    'worldbank',
]
```

Run migrations:

```bash
python manage.py migrate worldbank
```

## Quick Start

Import all data (countries, indicators, and default travel-context data):

```bash
python manage.py worldbank --import=all
```

Import specific categories:

```bash
python manage.py worldbank --import=data --category=tourism,economy
```

Import specific indicators:

```bash
python manage.py worldbank --import=data --indicators=SP.POP.TOTL,NY.GDP.PCAP.CD
```

## Configuration

Optional settings in `settings.py`:

```python
WORLDBANK = {
    # Year range for data import
    'START_YEAR': 2000,
    'END_YEAR': 2024,

    # Batch size for bulk operations
    'BATCH_SIZE': 1000,

    # API settings
    'TIMEOUT': 30,
    'PER_PAGE': 1000,

    # Default indicators (easily customizable)
    'DEFAULT_INDICATORS': [
        'SP.POP.TOTL',        # Total population
        'EN.POP.DNST',        # Population density
        'SP.URB.TOTL.IN.ZS',  # Urban population %
        'ST.INT.ARVL',        # International tourist arrivals
        'ST.INT.RCPT.CD',     # Tourism receipts
        'IT.NET.USER.ZS',     # Internet users %
        'IT.CEL.SETS.P2',     # Mobile subscriptions
        'EG.ELC.ACCS.ZS',     # Access to electricity
    ],
}
```

## Categories

| Category | Description | Example Indicators |
|----------|-------------|-------------------|
| `demographics` | Population, density, urbanization | SP.POP.TOTL, EN.POP.DNST |
| `tourism` | Tourist arrivals, receipts | ST.INT.ARVL, ST.INT.RCPT.CD |
| `connectivity` | Internet, mobile, electricity | IT.NET.USER.ZS, EG.ELC.ACCS.ZS |
| `economy` | GDP, GNI, inflation | NY.GDP.PCAP.CD, FP.CPI.TOTL.ZG |
| `health` | Life expectancy, healthcare | SP.DYN.LE00.IN, SH.MED.BEDS.ZS |
| `education` | Literacy, enrollment | SE.ADT.LITR.ZS, SE.SEC.ENRR |
| `labor` | Employment, unemployment | SL.TLF.CACT.ZS, SL.UEM.TOTL.ZS |
| `governance` | Rule of law, regulatory quality | IQ.RULE.LAW.XQ, IQ.REG.QUAL.XQ |
| `poverty` | Poverty rates, inequality | SI.POV.DDAY, SI.POV.GINI |
| `trade` | Imports, exports, FDI | NE.EXP.GNFS.ZS, BX.KLT.DINV.CD.WD |
| `environment` | CO2, energy, forests | EN.ATM.CO2E.PC, AG.LND.FRST.ZS |
| `agriculture` | Land use, crop yields | AG.LND.AGRI.ZS, AG.YLD.CREL.KG |

## Usage Examples

```python
from worldbank.models import Country, Indicator, IndicatorValue

# Get a country
usa = Country.objects.get(iso2_code='US')

# Get population data for USA
population = IndicatorValue.objects.filter(
    country=usa,
    indicator__code='SP.POP.TOTL',
).order_by('-year')

for val in population[:5]:
    print(f"{val.year}: {val.value:,.0f}")

# Compare GDP across countries
gdp = IndicatorValue.objects.filter(
    indicator__code='NY.GDP.PCAP.CD',
    year=2022,
    country__is_aggregate=False,
).select_related('country').order_by('-value')[:10]

for val in gdp:
    print(f"{val.country.name}: ${val.value:,.0f}")

# Get all tourism indicators for a country
tourism_data = IndicatorValue.objects.filter(
    country=usa,
    indicator__category='tourism',
    year=2022,
).select_related('indicator')

# Find high-income countries
high_income = Country.objects.filter(
    income_level='HIC',
    is_aggregate=False,
)
```

## Management Command

```bash
# Show help
python manage.py worldbank --help

# Import everything
python manage.py worldbank --import=all

# Import only countries and indicators metadata
python manage.py worldbank --import=country,indicator

# Import data for specific categories
python manage.py worldbank --import=data --category=tourism,demographics

# Import all categories
python manage.py worldbank --import=data --category=all

# Import specific indicators
python manage.py worldbank --import=data --indicators=SP.POP.TOTL,NY.GDP.PCAP.CD

# Specify year range
python manage.py worldbank --import=data --start-year=2010 --end-year=2023

# Flush and reimport
python manage.py worldbank --flush=all --import=all

# List available categories
python manage.py worldbank --list-categories

# List indicators
python manage.py worldbank --list-indicators

# Dry run (no database changes)
python manage.py worldbank --import=all --dry-run
```

## Data Source

Data is sourced from the [World Bank Open Data](https://data.worldbank.org/) API. The data is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) - commercial use is allowed with attribution.

## Disclaimer

This project is not affiliated with, endorsed by, or associated with the [World Bank](https://www.worldbank.org/) or the [World Bank Group](https://www.worldbankgroup.org/). It is an independent, third-party Django integration that consumes publicly available World Bank Open Data.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
