Skip to content

Getting Started

This guide will help you install the ODA Data Package and get your first ODA data in minutes.

Installation

The package requires Python 3.11 or higher. Install it using pip:

pip install oda-data --upgrade

Your First ODA Data

Set Up Data Storage

Before fetching data, tell the package where to cache downloaded files:

from oda_data import set_data_path

# This creates a folder to store cached data
set_data_path("data")

Choose Your Data Path

Pick a location where you want to cache ODA data. The package will create this folder if it doesn't exist. Cached data speeds up subsequent queries significantly.

Example 1: Get Total ODA

Let's get total ODA (net disbursements) for all donors from 2020 to 2022:

Get Total ODA for All Donors
from oda_data import OECDClient

# Create a client for specific years
client = OECDClient(years=range(2020, 2023))

# Get Total ODA data
data = client.get_indicators("DAC1.10.1010")

# View the results
print(data.head())

Output: 

   donor_code   donor_name  year      value
0       20000  DAC Members  2020  183776.35
1       20000  DAC Members  2021  205638.09
2       20000  DAC Members  2022  240675.09

Understanding the Data

The data includes values in millions of USD (current prices) by default. This is indicated by the unit_multiplier column (typically '6'). For example, a value of 3245.68 with unit_multiplier '6' means $3.246 billion.

Example 2: Filter by Specific Donors

Get bilateral ODA for France (code 4) and the USA (code 302):

Get Bilateral ODA for France and USA
from oda_data import OECDClient

client = OECDClient(
    years=[2021, 2022],
    providers=[4, 302]  # France and USA
)

data = client.get_indicators("DAC1.10.1015")  # Bilateral ODA

print(data[["donor_code", "year", "value"]])

Output: 

   donor_code  year      value
0           4  2021   10312.19
1           4  2022   10533.46
2         302  2021   38229.28
3         302  2022   52001.97

Values in Millions

The values shown are in millions of USD (unit_multiplier='6'). To get actual amounts, multiply by 1,000,000.

What's Next?

Now that you've fetched your first ODA data, you can:

Common Options

Here are some commonly used client options:

client = OECDClient(
    years=range(2018, 2023),           # Filter by year range
    providers=[4, 12, 302],            # Filter by donors (France, UK, USA)
    recipients=[249, 258],             # Filter by recipients (Kenya, Mozambique)
    currency="EUR",                    # Get data in Euros instead of USD
    base_year=2021,                    # Adjust to constant 2021 prices
    measure="grant_equivalent",        # Use grant equivalents instead of flows
    use_bulk_download=True             # Use bulk files for better performance (when accessing many indicators)
)

Finding Codes

Need to find provider or recipient codes?

from oda_data import OECDClient

# Get all available providers (returns dict of code: name)
providers = OECDClient.available_providers()
print(f"Total providers: {len(providers)}")

# Get all available recipients (returns dict of code: name)
recipients = OECDClient.available_recipients()
print(f"Total recipients: {len(recipients)}")

# Get all available currencies (returns list of currency codes)
currencies = OECDClient.available_currencies()
print(f"Available currencies: {currencies}")
# Returns: ['USD', 'EUR', 'GBP', 'CAD', 'LCU']

Currency Codes

  • USD: United States Dollars (default)
  • EUR: Euros
  • GBP: British Pounds
  • CAD: Canadian Dollars
  • LCU: Local Currency Units (donor's own currency)