django-worldbank

A Django application to download and import data from the World Bank Open Data 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

pip install django-worldbank

Add to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'worldbank',
]

Run migrations:

python manage.py migrate worldbank

Quick Start

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

python manage.py worldbank --import=all

Import specific categories:

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

Import specific indicators:

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

Configuration

Optional settings in settings.py:

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

Usage Examples

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

# 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 API. The data is licensed under CC BY 4.0 - commercial use is allowed with attribution.

Disclaimer

This project is not affiliated with, endorsed by, or associated with the World Bank or the World Bank Group. It is an independent, third-party Django integration that consumes publicly available World Bank Open Data.

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.