---
name: oecd
description: Access and retrieve economic, social, and statistical data from the OECD (Organisation for Economic Co-operation and Development) database. This skill enables querying 1,436+ datasets covering GDP, employment, education, health, trade, environment, and more through the OECD's SDMX-based REST API. Use this skill when you need official OECD statistics, international economic data, or comparative country analyses.
metadata:
  display_name: "OECD Data Access"
  short_description: "Access OECD economic and statistical data via API"
  default_prompt: "Get GDP data for USA from 2015-2023 from OECD"
  icon_path: "assets/icon.png"
---

# OECD Data Access Skill

Access official OECD (Organisation for Economic Co-operation and Development) statistical data through their SDMX-based REST API.

## Overview

The OECD provides **1,436+ datasets** covering:
- **Economic Indicators**: GDP, national accounts, fiscal policy (353 datasets)
- **Labour & Employment**: Unemployment, wages, workforce statistics (167 datasets)
- **Education**: PISA scores, education spending, student performance (100 datasets)
- **Demographics**: Population, migration, age distribution (82 datasets)
- **Health**: Health expenditure, hospital data, mortality (81 datasets)
- **Trade**: Imports, exports, merchandise trade (46 datasets)
- **Environment**: Climate, emissions, pollution (53 datasets)
- And many more topics...

## When to Use This Skill

Use this skill when you need:
- Official OECD economic statistics and indicators
- International comparative data across countries
- GDP, unemployment, or other macroeconomic data
- Education statistics (PISA, education spending)
- Health system data and expenditure
- Trade and fiscal policy data
- Environmental and climate statistics
- Demographic and migration data

## Invocation

The user may invoke this skill with phrases like:
- "Get GDP data for USA from OECD"
- "Show me unemployment rates for G7 countries"
- "Find OECD education statistics for Finland"
- "Compare health expenditure across OECD countries"
- "Get trade data from OECD database"

## Notes

- `get_gdp_data()` returns annual GDP measures (nominal, real, per capita, growth) from National Accounts at a Glance for the chosen countries. For quarterly data use `get_data()` with a quarterly National Accounts dataflow.
- The dataset catalog (`search_datasets()`, `list_available_topics()`, `list_datasets_by_topic()`, `get_dataset_info()`) is built from the live OECD dataflow list on first use and cached for 7 days in `~/.cache/oecd_skill/`. Topics are assigned by keyword matching, so treat them as a guide.
- A 404 from the OECD API often means no data matched the filter, not that the dataset is missing. Retry with `filter_expression="all"` and filter the result locally.

## Workflow (STRICT)

### Step 1: Load the API Wrapper

First, ensure the OECD API wrapper is imported:

```python
import sys
sys.path.insert(0, '/workspace/skills/oecd/scripts')
from oecd_api_wrapper import OECDDataAPI, OECDCountries

# Initialize API
api = OECDDataAPI()
```

### Step 2: Discover Datasets (If Needed)

The API includes dataset discovery methods to help find the right data:

**Browse by Topic:**
```python
# List available topics
topics = api.list_available_topics()

# Get datasets in a topic
education_datasets = api.list_datasets_by_topic('Education')
```

**Search for Datasets:**
```python
# Search by keyword
gdp_datasets = api.search_datasets('GDP')
unemployment_datasets = api.search_datasets('unemployment')
```

**Get Popular Datasets:**
```python
# Get recommended datasets for a topic
popular = api.get_popular_datasets(topic='Economy & Finance', limit=10)
```

**Get Dataset Info:**
```python
# Get details about a specific dataset
info = api.get_dataset_info('DSD_NAAG@DF_NAAG_I')
print(f"Name: {info['name']}")
print(f"Agency: {info['agency']}")
```

### Step 3: Retrieve Data

Once you know which dataset to use, retrieve the data:

**Using Convenience Methods:**

```python
# GDP data for specific countries
gdp_data = api.get_gdp_data(
    countries=['USA', 'GBR', 'FRA'],
    start_period='2015',
    end_period='2023',
    frequency='A'  # 'A' = Annual, 'Q' = Quarterly
)
```

**Using Generic Data Retrieval:**

```python
# Query any OECD dataset
data = api.get_data(
    agency='OECD.SDD.NAD',
    dataset='DSD_NAAG@DF_NAAG_I',
    filter_expression='AUS+NZL',  # Australia + New Zealand
    start_period='2020',
    end_period='2023',
    format_type='csvfilewithlabels'
)
```

### Step 4: Process and Present Results

The API returns pandas DataFrames for easy analysis:

```python
# Display data
print(data.head())

# Save to file if needed
data.to_csv('oecd_data.csv', index=False)

# Analyze or visualize
# ... perform analysis
```

## Key Methods Reference

### Dataset Discovery

| Method | Purpose | Example |
|--------|---------|---------|
| `list_available_topics()` | List 17 available topics | `api.list_available_topics()` |
| `list_datasets_by_topic(topic)` | Browse datasets in a topic | `api.list_datasets_by_topic('Health')` |
| `list_datasets_by_agency(agency)` | Browse by managing agency | `api.list_datasets_by_agency('OECD.SDD.NAD')` |
| `search_datasets(keyword)` | Search for datasets | `api.search_datasets('PISA')` |
| `get_popular_datasets(topic, limit)` | Get recommended datasets | `api.get_popular_datasets('Education', 10)` |
| `get_dataset_info(dataset_id)` | Get dataset details | `api.get_dataset_info('DSD_NAAG@DF_NAAG_I')` |

### Data Retrieval

| Method | Purpose | Parameters |
|--------|---------|------------|
| `get_gdp_data()` | Get GDP data | countries, start_period, end_period, frequency |
| `get_data()` | Generic data query | agency, dataset, filter_expression, start_period, end_period |
| `get_structure()` | Get dataset metadata | agency, dataset, version |

### Country Helpers

```python
# Get all country codes
all_codes = OECDCountries.get_all_codes()

# Get OECD member countries
members = OECDCountries.get_oecd_members()

# Look up country name
name = OECDCountries.get_name('USA')  # Returns: 'United States'
```

## Common Dataset IDs

| Dataset ID | Description | Agency |
|------------|-------------|--------|
| `DSD_NAAG@DF_NAAG_I` | National Accounts at a Glance | OECD.SDD.NAD |
| `DSD_LFS@DF_IALFS_UNE_M` | Labour Force Statistics - Unemployment | OECD |
| `DSD_PISA@DF_PISA_2022` | PISA Education Results | OECD.EDU.IMEP |
| `DSD_SHA@DF_SHA` | Health Expenditure | OECD.ELS.HD |
| `DSD_BIMTS@DF_BIMTS_M` | Balanced International Merchandise Trade | OECD |
| `DSD_REV@DF_REV` | Revenue Statistics | OECD.CTP.TPS |

## Dataset Naming Convention

OECD datasets follow this pattern: `DSD_FAMILY@DF_SPECIFIC`

- **DSD** = Data Structure Definition
- **FAMILY** = Dataset family code (e.g., NAAG, LFS, PISA)
- **DF** = Dataflow
- **SPECIFIC** = Specific dataset within the family

Example: `DSD_NAAG@DF_NAAG_I`
- Family: NAAG (National Accounts at a Glance)
- Specific: NAAG_I (Part I - GDP indicators)

## Topic Categories

**17 Available Topics:**
1. Economy & Finance (353 datasets)
2. Labour & Employment (167 datasets)
3. Education (100 datasets)
4. Demographics (82 datasets)
5. Health (81 datasets)
6. National Accounts (57 datasets)
7. Environment (53 datasets)
8. Prices & Inflation (50 datasets)
9. Trade (46 datasets)
10. Social (43 datasets)
11. Innovation & R&D (43 datasets)
12. Development (39 datasets)
13. Government (28 datasets)
14. Regional (16 datasets)
15. Industry (5 datasets)
16. Agriculture (4 datasets)
17. Other (269 datasets)

## Common Country Codes

**OECD Members:** AUS, AUT, BEL, CAN, CHL, COL, CRI, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, ISL, IRL, ISR, ITA, JPN, KOR, LVA, LTU, LUX, MEX, NLD, NZL, NOR, POL, PRT, SVK, SVN, ESP, SWE, CHE, TUR, GBR, USA

**Other Major Economies:** CHN (China), IND (India), BRA (Brazil), RUS (Russia), ZAF (South Africa)

## Error Handling

```python
try:
    data = api.get_gdp_data(countries=['USA'], start_period='2015', end_period='2023')
    print(f"Retrieved {len(data)} records")
except Exception as e:
    print(f"Error retrieving data: {e}")
    # Try alternative approach or dataset
```

## Best Practices

1. **Start with Dataset Discovery**: Use search/browse methods before attempting data retrieval
2. **Use Specific Filters**: Narrow down data with country codes and time periods
3. **Check Dataset Info**: Verify dataset structure before querying
4. **Handle Rate Limits**: The API includes automatic rate limiting (0.5s delay)
5. **Save Results**: Export data to CSV for further analysis
6. **Refer to Documentation**: See references for detailed dataset guides

## Output Format (STRICT)

When presenting OECD data:
1. **Clearly State the Source**: "According to OECD data..."
2. **Include Time Period**: Specify the years/quarters covered
3. **Note Data Format**: Annual, quarterly, monthly, etc.
4. **Provide Context**: Explain what the indicators mean
5. **Save Data Files**: Export to CSV when datasets are large
6. **Visualize When Appropriate**: Create charts for trends

## Constraints

- Rate limit: 0.5 seconds between API calls (automatically handled)
- Some datasets may require specific filter expressions
- Historical data availability varies by dataset
- Not all countries are available in all datasets
- Dataset catalog requires initial loading (catalog files in `oecd_data_output/`)
- MUST use the provided API wrapper methods - do not construct raw API calls
- MUST handle errors gracefully with try/except blocks
- If dataset catalog files are missing, may need to run `parse_oecd_dataflows.py` first

## Examples

**Example 1: Get GDP data for USA**
```
User: /oecd Get GDP data for USA from 2015 to 2023

Agent workflow:
1. Import and initialize API
2. Call api.get_gdp_data(countries=['USA'], start_period='2015', end_period='2023', frequency='A')
3. Present results in a clear format
4. Save to CSV if dataset is large

Expected output: DataFrame with USA GDP data, properly formatted and explained
```

**Example 2: Compare unemployment across countries**
```
User: /oecd Show unemployment rates for G7 countries since 2020

Agent workflow:
1. Initialize API
2. Search for unemployment datasets: api.search_datasets('unemployment')
3. Identify appropriate dataset (e.g., DSD_LFS@DF_IALFS_UNE_M)
4. Retrieve data for G7 countries: ['USA', 'GBR', 'FRA', 'DEU', 'ITA', 'JPN', 'CAN']
5. Present comparative analysis

Expected output: Unemployment data comparison with context and insights
```

**Example 3: Find education statistics**
```
User: /oecd Find OECD education data for Finland

Agent workflow:
1. Initialize API
2. Browse education datasets: api.list_datasets_by_topic('Education')
3. Show available datasets to user
4. If specific dataset requested, retrieve and present data

Expected output: List of available education datasets or specific data if identified
```

## References

See the `references/` directory for:
- `OECD_DATASETS_GUIDE.md` - Detailed dataset organization and structure
- `README_OECD_API.md` - Complete API documentation and usage examples
- `DATASET_DISCOVERY_SUMMARY.md` - Project summary and dataset catalog information

External links:
- OECD Data Explorer: https://data-explorer.oecd.org/
- OECD API Documentation: https://www.oecd.org/en/data/insights/data-explainers/2024/09/api.html

## Success Criteria

✓ Successfully query OECD API and retrieve data
✓ Return data in pandas DataFrame format
✓ Provide clear explanations of the data
✓ Include source attribution (OECD)
✓ Save data files when datasets are large
✓ Handle errors gracefully with fallback options