OPEC Data Skill

Never hardcode or log the key. Pass it as a query parameter ?api_key=<KEY>.

Reading the credentials file (bash):

KEY=$(grep '^api_key=' ~/.config/eia/credentials 2>/dev/null | cut -d= -f2)
[ -z "$KEY" ] && KEY="${EIA_API_KEY}"

API Structure

STEO Dataset (Aggregates + Forecasts)

Base URL: https://api.eia.gov/v2/steo/data/

Returns monthly data series by seriesId. Each series has historical values and 18-month EIA forecasts.

Key parameters:

Example (OPEC total production, last 12 months):

KEY=$(grep '^api_key=' ~/.config/eia/credentials 2>/dev/null | cut -d= -f2)
curl -s -G "https://api.eia.gov/v2/steo/data/" \
  --data-urlencode "api_key=${KEY}" \
  --data-urlencode "frequency=monthly" \
  --data-urlencode "facets[seriesId][]=COPR_OPEC" \
  --data-urlencode "data[]=value" \
  --data-urlencode "sort[0][column]=period" \
  --data-urlencode "sort[0][direction]=desc" \
  --data-urlencode "length=12"

International Dataset (Per-Country)

Base URL: https://api.eia.gov/v2/international/data/

Returns per-country production, consumption, imports, and exports.

Key parameters:

Example (Saudi Arabia crude production, annual):

curl -s -G "https://api.eia.gov/v2/international/data/" \
  --data-urlencode "api_key=${KEY}" \
  --data-urlencode "frequency=annual" \
  --data-urlencode "facets[countryRegionId][]=SAU" \
  --data-urlencode "facets[productId][]=57" \
  --data-urlencode "facets[activityId][]=1" \
  --data-urlencode "facets[unit][]=TBPD" \
  --data-urlencode "data[]=value" \
  --data-urlencode "sort[0][column]=period" \
  --data-urlencode "sort[0][direction]=desc" \
  --data-urlencode "length=10"

Key STEO Series IDs

OPEC Production

OPEC Capacity and Spare

OPEC Liquids (incl. NGLs and condensate)

Supply Disruptions

Benchmark Crude Prices

OPEC Member Countries

Current OPEC members (13) and their EIA International countryRegionId codes:

OPEC+ non-OPEC participants include Russia (RUS), Kazakhstan (KAZ), Mexico (MEX), Oman (OMN), Azerbaijan (AZE), Malaysia (MYS), Bahrain (BHR), Brunei (BRN), Sudan (SDN), South Sudan (SSD).

Workflow

Step 1 -- Resolve Intent

Map the user's question to the appropriate dataset:

Step 2 -- Fetch Data

Build the URL with appropriate filters. Default behavior:

• Use frequency=monthly unless user asks for annual
• Sort by period desc to get most recent first
• Request 24 months of data by default
• STEO includes forecast data (future months) -- note which values are forecasts

Step 3 -- Parse Response

Response structure:

{
  "response": {
    "total": 420,
    "dateFormat": "YYYY-MM",
    "frequency": "monthly",
    "data": [
      {
        "period": "2025-01",
        "seriesId": "COPR_OPEC",
        "seriesDescription": "Crude Oil Production, OPEC Total",
        "value": 27.123,
        "unit": "million barrels per day"
      }
    ]
  }
}

Step 4 -- Produce Output

Format: Raw Data Table + Narrative

Present a markdown table of the most relevant rows (cap at ~20 rows), then a narrative summary covering:

1. Current state -- most recent actual value(s) and date
2. Trend -- direction and magnitude over the time window (use delta in mbd)
3. Capacity and spare -- if relevant, show how much headroom OPEC has
4. OPEC+ context -- note quota compliance if discussing production levels
5. Forecast -- clearly label EIA forecast values vs historical actuals
6. Units and caveats -- always state units; note STEO forecast uncertainty

Example output structure:

## OPEC Crude Oil Production (Monthly, 2023-2025)

| Period  | Production (million bbl/d) | Type     |
|---------|---------------------------|----------|
| 2025-06 | 28.10                     | Forecast |
| 2025-05 | 27.95                     | Forecast |
| 2025-01 | 27.12                     | Actual   |
| 2024-12 | 27.05                     | Actual   |
| ...     | ...                       | ...      |

**Summary:** OPEC produced 27.12 million bbl/d in January 2025, down 0.3 mbd
from the prior year. EIA forecasts a recovery to 28.1 mbd by mid-2025 as
voluntary cuts are gradually unwound. Spare capacity stands at 4.2 mbd (Jan 2025),
concentrated in Saudi Arabia and the UAE. Data: EIA Short-Term Energy Outlook.

Error Handling

Caveats and Data Limitations

• No direct OPEC API: All OPEC web properties (opec.org, asb.opec.org, momr.opec.org) are behind Cloudflare challenges. This skill uses EIA as a high-quality secondary source for OPEC data.
• OPEC basket price: The OPEC Reference Basket price is not available in EIA. Use Brent (BREPUUS) as the closest proxy. The actual OPEC basket tracks a weighted average of member crude grades.
• Quota compliance: EIA does not publish OPEC quota targets or compliance ratios. Production data can be compared against publicly announced targets.
• Forecast vs actual: STEO data includes EIA forecasts for future months. Always distinguish forecasts from actuals. Forecasts are updated monthly.
• Revisions: Recent months (1-2 most recent) may be revised.
• Country-level lag: EIA International annual data may lag 1-2 years behind current. Monthly STEO aggregates are more current.

Implementation Notes

• Use curl with --data-urlencode for all bracket-containing parameters to avoid shell escaping issues.
• STEO data is updated monthly, typically in the first week of each month.
• For multi-series comparisons (e.g., OPEC production vs spare capacity), make parallel requests for each series and merge on the period field.
• See references/api_reference.md for the full series catalog.
• See references/python_example.py for a stdlib-only client example.