OECD data

What the skill tells Claude

This is the skill's instruction file, SKILL.md, as Claude reads it.

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:

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:

# List available topics
topics = api.list_available_topics()

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

Search for Datasets:

# Search by keyword
gdp_datasets = api.search_datasets('GDP')
unemployment_datasets = api.search_datasets('unemployment')

Get Popular Datasets:

# Get recommended datasets for a topic
popular = api.get_popular_datasets(topic='Economy & Finance', limit=10)

Get Dataset Info:

# 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:

# 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:

# 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:

# 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

Data Retrieval

Country Helpers

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

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

Shared as is, with no warranty. Not investment, legal or tax advice. See Disclosures.