Getting Started with Energy Intelligence

Energy Intelligence transforms official government and industry energy reports into structured JSON you can query via API. Stop parsing PDFs and Excel files manually.

Time to first request: ~5 minutes

Prerequisites

  1. Reservoir Mastery subscription ($129/month) - Upgrade here
  2. API Key - Available in your Dashboard

Step 1: Get Your API Key

  1. Log into oilpriceapi.com/dashboard
  2. Copy your API key from the dashboard
  3. Store it securely (never commit to source control)

Step 2: Make Your First Request

Test your access with the latest rig count data:

cURL

curl "https://api.oilpriceapi.com/v1/ei/rig_counts/latest" \
  -H "Authorization: Token YOUR_API_KEY"

Python

import requests

API_KEY = "YOUR_API_KEY"  # Store in environment variable

response = requests.get(
    "https://api.oilpriceapi.com/v1/ei/rig_counts/latest",
    headers={"Authorization": f"Token {API_KEY}"}
)

data = response.json()
print(f"US Total Rigs: {data['data']['us_total']}")
print(f"Permian Basin: {data['data']['basins']['permian']}")

JavaScript

const API_KEY = process.env.OILPRICEAPI_KEY;

const response = await fetch(
  "https://api.oilpriceapi.com/v1/ei/rig_counts/latest",
  {
    headers: { "Authorization": `Token ${API_KEY}` }
  }
);

const { data } = await response.json();
console.log(`US Total Rigs: ${data.us_total}`);
console.log(`Permian Basin: ${data.basins.permian}`);

Step 3: Understand the Response

All Energy Intelligence endpoints return this format:

{
  "data": {
    "report_date": "2025-01-03",
    "us_total": 584,
    "basins": {
      "permian": { "count": 298, "week_over_week": -2 },
      "eagle_ford": { "count": 48, "week_over_week": 0 }
    }
  },
  "meta": {
    "page": 1,
    "per_page": 10,
    "total_count": 1,
    "api_version": "v1",
    "tier_required": "reservoir_mastery",
    "cache_ttl": 3600
  }
}

Key Fields

FieldDescription
dataThe actual data payload
meta.tier_requiredConfirms Reservoir Mastery tier
meta.cache_ttlSeconds until data refreshes

Step 4: Explore Available Data

Energy Intelligence includes 5 data categories:

1. Rig Counts (Baker Hughes)

Weekly drilling activity by basin and state.

# Latest rig count
requests.get("https://api.oilpriceapi.com/v1/ei/rig_counts/latest")

# Filter by basin
requests.get("https://api.oilpriceapi.com/v1/ei/rig_counts/by_basin",
             params={"basins": "permian,bakken"})

# Historical data
requests.get("https://api.oilpriceapi.com/v1/ei/rig_counts/historical",
             params={"region": "permian", "weeks": 52})

Release: Every Friday at 1:00 PM ET

2. Oil Inventories (EIA WPSR)

Crude stocks, Cushing storage, and product inventories.

# Latest inventories
requests.get("https://api.oilpriceapi.com/v1/ei/oil_inventories/latest")

# Cushing storage (52-week history)
requests.get("https://api.oilpriceapi.com/v1/ei/oil_inventories/cushing",
             params={"weeks": 52})

# Filter by product type
requests.get("https://api.oilpriceapi.com/v1/ei/oil_inventories/by_product",
             params={"product": "crude"})

Release: Every Wednesday at 10:30 AM ET

3. OPEC Production

Country-level production and compliance data.

# Latest production
requests.get("https://api.oilpriceapi.com/v1/ei/opec_productions/latest")

# Top producers
requests.get("https://api.oilpriceapi.com/v1/ei/opec_productions/top_producers",
             params={"limit": 5})

# Specific country
requests.get("https://api.oilpriceapi.com/v1/ei/opec_productions/by_country",
             params={"country": "saudi_arabia"})

Release: ~15th of each month

4. Drilling Productivity (EIA DPR)

DUC wells and new well productivity by basin.

# DUC wells by basin
requests.get("https://api.oilpriceapi.com/v1/ei/drilling_productivities/duc_wells")

# Basin-specific data
requests.get("https://api.oilpriceapi.com/v1/ei/drilling_productivities/by_basin",
             params={"basin": "permian"})

Release: ~15th of each month

5. Forecasts (EIA STEO)

Official price and production forecasts.

# Latest forecasts
requests.get("https://api.oilpriceapi.com/v1/ei/forecasts/latest")

# Price forecasts
requests.get("https://api.oilpriceapi.com/v1/ei/forecasts/prices")

Release: 1st Tuesday of each month

Step 5: Common Query Patterns

Monitor Weekly Rig Count Changes

# Get 4 weeks of data to track trends
response = requests.get(
    "https://api.oilpriceapi.com/v1/ei/rig_counts/historical",
    headers={"Authorization": f"Token {API_KEY}"},
    params={"region": "us", "weeks": 4}
)

for week in response.json()['data']['history']:
    print(f"{week['date']}: {week['count']} rigs ({week['wow']:+d})")

Track Cushing Inventory Levels

# Monitor Cushing storage vs. 5-year average
response = requests.get(
    "https://api.oilpriceapi.com/v1/ei/oil_inventories/cushing",
    headers={"Authorization": f"Token {API_KEY}"},
    params={"weeks": 52, "include_5yr_avg": True}
)

data = response.json()['data']
print(f"Current: {data['latest']['volume']} MMbbl")
print(f"5-Year Avg: {data['five_year_avg']} MMbbl")

Compare OPEC Production vs Quotas

# Check OPEC+ compliance
response = requests.get(
    "https://api.oilpriceapi.com/v1/ei/opec_productions/latest",
    headers={"Authorization": f"Token {API_KEY}"}
)

data = response.json()['data']
print(f"Total OPEC: {data['total_mbpd']} mb/d")
print(f"Compliance: {data['compliance_pct']}%")

Error Handling

Common Errors

HTTP CodeMeaningSolution
401Invalid API keyCheck your API key is correct
403Insufficient tierUpgrade to Reservoir Mastery
429Rate limitedReduce request frequency
500Server errorRetry with exponential backoff

Example Error Response

{
  "error": "This endpoint requires Reservoir Mastery tier",
  "code": "insufficient_tier",
  "upgrade_url": "https://oilpriceapi.com/pricing"
}

Handling Errors in Code

response = requests.get(url, headers=headers)

if response.status_code == 403:
    print("Upgrade to Reservoir Mastery for Energy Intelligence access")
    print(response.json().get('upgrade_url'))
elif response.status_code == 429:
    # Implement exponential backoff
    time.sleep(60)
    response = requests.get(url, headers=headers)
elif response.status_code >= 500:
    # Retry logic
    for attempt in range(3):
        time.sleep(2 ** attempt)
        response = requests.get(url, headers=headers)
        if response.ok:
            break

Rate Limits

Reservoir Mastery tier includes:

  • 250,000 requests/month for all endpoints
  • No per-minute limits for normal usage
  • Bulk/historical queries supported

Data Freshness

SourceUpdate Latency
Baker Hughes< 30 min after release
EIA WPSR< 15 min after release
OPEC MOMR< 2 hours after release
EIA DPR< 1 hour after release
EIA STEO< 1 hour after release

Next Steps

Support

Need help? Contact us: