Analytics API

Statistical analysis and technical indicators for commodity price data.

Tier Required: Production Boost ($45/mo) or Reservoir Mastery ($129/mo)

Endpoints

Method	Endpoint	Description	Tier
GET	`/v1/analytics/statistics`	Z-score, percentile, volatility	Production Boost
GET	`/v1/analytics/correlation`	Correlation analysis	Production Boost
GET	`/v1/analytics/trend`	Technical analysis	Production Boost
GET	`/v1/analytics/spread`	Spread analysis	Production Boost
GET	`/v1/analytics/forecast`	Price forecasting	Reservoir Mastery
GET	`/v1/analytics/performance`	Your API usage analytics	All tiers

Statistics

Calculate statistical metrics for any commodity.

GET /v1/analytics/statistics

Parameters

Parameter	Type	Required	Default	Description
`code`	string	Yes	-	Commodity code (e.g., `WTI_USD`)
`period`	integer	No	30	Analysis period in days

Response

{
  "code": "WTI_USD",
  "period": 30,
  "statistics": {
    "z_score": 1.45,
    "z_score_interpretation": "Price is 1.45 standard deviations above the mean",
    "percentile": 87.5,
    "percentile_interpretation": "Current price is higher than 87.5% of prices in this period",
    "volatility": 2.34,
    "volatility_interpretation": "Moderate volatility"
  },
  "tier": "production_boost"
}

Z-Score Interpretation

Z-Score Range	Interpretation
< -2	Extremely oversold
-2 to -1	Below average
-1 to 1	Normal range
1 to 2	Above average
> 2	Extremely overbought

Correlation

Analyze price relationships between commodities.

GET /v1/analytics/correlation

Parameters

Parameter	Type	Required	Description
`code1`	string	Yes*	First commodity code
`code2`	string	Yes*	Second commodity code
`period`	integer	No	Days (default: 30)
`type`	string	No	`analysis`, `matrix`, or `rolling`
`codes`	string	For matrix	Comma-separated codes
`window`	integer	For rolling	Window size (default: 7)

*Required for analysis type

Analysis Response (default)

{
  "type": "analysis",
  "code1": "WTI_USD",
  "code2": "BRENT_CRUDE_USD",
  "period": 30,
  "correlation": 0.94,
  "correlation_interpretation": "Very strong positive correlation",
  "strength": "very_strong",
  "direction": "positive",
  "stability": 0.89,
  "tier": "production_boost"
}

Matrix Response

GET /v1/analytics/correlation?type=matrix&codes=WTI_USD,BRENT_CRUDE_USD,NATURAL_GAS_USD

{
  "type": "matrix",
  "codes": ["WTI_USD", "BRENT_CRUDE_USD", "NATURAL_GAS_USD"],
  "period": 30,
  "matrix": {
    "WTI_USD": {
      "WTI_USD": 1.00,
      "BRENT_CRUDE_USD": 0.94,
      "NATURAL_GAS_USD": 0.23
    },
    "BRENT_CRUDE_USD": {
      "WTI_USD": 0.94,
      "BRENT_CRUDE_USD": 1.00,
      "NATURAL_GAS_USD": 0.21
    }
  }
}

Correlation Strength

Range	Strength
0.9 - 1.0	Very Strong
0.7 - 0.9	Strong
0.4 - 0.7	Moderate
0.2 - 0.4	Weak
0.0 - 0.2	None

Trend Analysis

Technical indicators and trend analysis.

GET /v1/analytics/trend

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Commodity code
`period`	integer	No	Days (default: 30)
`type`	string	No	`analysis`, `sma`, `ema`, `rsi`, or `levels`
`window`	integer	No	MA window (default: 20 for MA, 14 for RSI)

Analysis Response (default)

{
  "type": "analysis",
  "code": "WTI_USD",
  "period": 30,
  "trend": {
    "direction": "bullish",
    "strength": "moderate",
    "slope": 0.15,
    "price_change_pct": 4.5
  },
  "momentum": {
    "rsi": 62.5,
    "interpretation": "Neutral (not overbought/oversold)"
  },
  "moving_averages": {
    "sma_20": 72.45,
    "ema_20": 73.12,
    "price_vs_sma": "above",
    "golden_cross": false
  },
  "levels": {
    "support": [70.50, 68.25],
    "resistance": [75.80, 78.00],
    "pivot_point": 73.15
  },
  "signal": {
    "value": 0.65,
    "interpretation": "Moderately bullish"
  },
  "tier": "production_boost"
}

RSI Interpretation

RSI Range	Interpretation
> 70	Overbought
50 - 70	Bullish momentum
30 - 50	Bearish momentum
< 30	Oversold

Spread Analysis

Analyze price spreads between related commodities.

GET /v1/analytics/spread

Parameters

Parameter	Type	Required	Description
`spread`	string	No	Spread identifier (see below)
`period`	integer	No	Days (default: 30)
`type`	string	No	`current` or `historical`

Available Spreads

Spread ID	Description	Unit
`wti_brent`	WTI-Brent basis spread	USD/barrel
`wti_dubai`	WTI-Dubai basis spread	USD/barrel
`321`	3-2-1 crack spread	USD/barrel
`gasoline_crack`	Gasoline crack spread	USD/barrel
`heating_oil_crack`	Heating oil crack spread	USD/barrel
`gas_oil_ratio`	Natural gas to oil ratio	Thermal equivalent

List Available Spreads

GET /v1/analytics/spread

{
  "available_spreads": [
    {
      "id": "wti_brent",
      "name": "WTI-Brent Spread",
      "description": "Price differential between WTI and Brent crude",
      "unit": "USD/barrel"
    }
  ],
  "usage": "GET /v1/analytics/spread?spread=wti_brent"
}

Current Spread Response

GET /v1/analytics/spread?spread=wti_brent

{
  "spread_name": "WTI-Brent Spread",
  "code1": "WTI_USD",
  "code2": "BRENT_CRUDE_USD",
  "price1": 73.25,
  "price2": 78.45,
  "current_spread": -5.20,
  "unit": "USD/barrel",
  "historical": {
    "mean": -4.85,
    "std_dev": 1.23,
    "min": -8.50,
    "max": -2.10,
    "percentile": 35.2,
    "z_score": -0.28,
    "data_points": 30
  },
  "interpretation": "Spread is near historical average",
  "tier": "production_boost"
}

Forecast

Statistical price forecasting (Reservoir Mastery tier only).

GET /v1/analytics/forecast

Parameters

Parameter	Type	Required	Description
`code`	string	No	Commodity code
`method`	string	No	`sma`, `ema`, or `combined` (default: `ema`)
`period`	integer	No	Lookback period (default: 90)

Methods

Method	Best For
`sma`	Stable, low-volatility markets
`ema`	Trending markets
`combined`	Uncertain market conditions

Forecast Response

{
  "code": "WTI_USD",
  "method": "ema",
  "current_price": 73.25,
  "data_points": 90,
  "volatility": 0.023,
  "forecasts": [
    {
      "horizon_days": 1,
      "forecast_value": 73.42,
      "forecast_change_pct": 0.23,
      "confidence_intervals": {
        "sigma_1": { "low": 71.75, "high": 75.09, "probability": 0.68 },
        "sigma_2": { "low": 70.08, "high": 76.76, "probability": 0.95 }
      }
    },
    {
      "horizon_days": 7,
      "forecast_value": 74.15,
      "forecast_change_pct": 1.23,
      "confidence_intervals": {
        "sigma_1": { "low": 69.85, "high": 78.45, "probability": 0.68 },
        "sigma_2": { "low": 65.55, "high": 82.75, "probability": 0.95 }
      }
    },
    {
      "horizon_days": 30,
      "forecast_value": 75.80,
      "forecast_change_pct": 3.48,
      "confidence_intervals": {
        "sigma_1": { "low": 65.25, "high": 86.35, "probability": 0.68 },
        "sigma_2": { "low": 54.70, "high": 96.90, "probability": 0.95 }
      }
    }
  ],
  "disclaimer": "Statistical projection based on historical data. Not financial advice.",
  "generated_at": "2025-01-10T14:30:00Z",
  "tier": "reservoir_mastery"
}

Performance (Usage Analytics)

Your API usage analytics (available to all tiers).

GET /v1/analytics/performance

Parameters

Parameter	Type	Default	Description
`range`	string	`30d`	Time range: `7d`, `30d`, `90d`

Response

{
  "overview": {
    "totalRequests": 15420,
    "monthlyRequests": 12350,
    "dailyAverage": 514,
    "peakDay": "2025-01-08",
    "peakHour": 14,
    "uniqueEndpoints": 8,
    "errorRate": 0.12,
    "avgResponseTime": 145
  },
  "dailyUsage": [
    { "date": "2025-01-10", "requests": 520, "errors": 1 },
    { "date": "2025-01-09", "requests": 485, "errors": 0 }
  ],
  "hourlyDistribution": [
    { "hour": 0, "requests": 12 },
    { "hour": 14, "requests": 89 }
  ],
  "endpointBreakdown": [
    { "endpoint": "/v1/prices/latest", "requests": 8500, "percentage": 55.1 },
    { "endpoint": "/v1/prices/historical", "requests": 3200, "percentage": 20.8 }
  ],
  "geographicData": [
    { "country": "US", "requests": 9800 },
    { "country": "UK", "requests": 2400 }
  ]
}

Code Examples

Python - Statistical Analysis

import requests

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Token {api_key}"}

# Get WTI statistics
response = requests.get(
    "https://api.oilpriceapi.com/v1/analytics/statistics",
    headers=headers,
    params={"code": "WTI_USD", "period": 30}
)
stats = response.json()

print(f"WTI Z-Score: {stats['statistics']['z_score']}")
print(f"Percentile: {stats['statistics']['percentile']}%")
print(f"Volatility: {stats['statistics']['volatility']}%")

JavaScript - Correlation Matrix

const response = await fetch(
  "https://api.oilpriceapi.com/v1/analytics/correlation?" +
  "type=matrix&codes=WTI_USD,BRENT_CRUDE_USD,NATURAL_GAS_USD,HEATING_OIL_USD",
  { headers: { "Authorization": "Token YOUR_API_KEY" } }
);
const data = await response.json();

// Print correlation matrix
const codes = data.codes;
console.log("        " + codes.join("  "));
codes.forEach(code1 => {
  const row = codes.map(code2 => data.matrix[code1][code2].toFixed(2));
  console.log(`${code1.padEnd(8)} ${row.join("  ")}`);
});

Dark Data API - Fundamental data
Prices API - Current prices
Futures API - Futures data