API Documentation

Complete reference for the Fuel Data Lab API

Quick Navigation

Quick Start Authentication Pricing Response Format Catalog & Series Price Data Signals & Metrics Events Regional Analysis Pattern Analysis Simulations Data Schemas

Quick Start

Get up and running in 30 seconds

1. Get the latest diesel price:

curl "https://fueldatalab.com/api/v1/prices/latest?product=diesel&geo_type=national" \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Response:

{
  "product": "diesel",
  "geo_type": "national", 
  "geo_code": "US",
  "period": "2024-12-21",
  "value": 3.578,
  "unit": "dollars_per_gallon",
  "delta_1w": -0.024
}

Get Your API Key

Authentication

All endpoints require a valid API key in the Authorization header:

Authorization: Bearer fsk_xxxxxxxxxxxxxxxxxxxx

Security: Keep your API keys secret. Never expose them in client-side code.

API Pricing

Three tiers based on usage needs:

Integrator$19/mo · 100K units

Analyst$49/mo · 500K units

Platform$149/mo · 2M units

1 unit = 1 API call. Returns 429 when exhausted.

Error Codes

400

Bad Request — Invalid parameters

401

Unauthorized — Invalid API key

429

Too Many Requests — Limit exhausted

500

Internal Error — Contact support

Response Format

Success:

{
  "data": { ... },
  "meta": {
    "count": 52,
    "limit": 100
  }
}

Error:

{
  "error": "Description",
  "code": "ERROR_CODE"
}

Catalog & Series

Discover available data

GET

/api/v1/catalog

List all available products, geographies, and canonical series.

curl "https://fueldatalab.com/api/v1/catalog" -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/series

Query fuel series by product, geography.

Parameters: product,geo_type,geo_code,canonical=1

curl "https://fueldatalab.com/api/v1/series?product=diesel&geo_type=national&canonical=1" \
  -H "Authorization: Bearer YOUR_KEY"

Price Data

Historical and current prices

GET

/api/v1/prices/latest

Get the most recent price for a product/region.

Parameters: product,geo_type,geo_code

curl "https://fueldatalab.com/api/v1/prices/latest?product=diesel&geo_type=national" \
  -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/prices

Get price history for a specific series.

Parameters: series_id (required),start,end,limit

curl "https://fueldatalab.com/api/v1/prices?series_id=UUID&limit=52" \
  -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/prices/series

Get price history by product/geo instead of series_id.

Signals & Metrics

Computed analytics and indicators

GET

/api/v1/metrics

Get computed metrics (deltas, volatility, percentiles).

Parameters: series_id (required),period,metrics (comma-separated)

curl "https://fueldatalab.com/api/v1/metrics?series_id=UUID&metrics=delta_1w,volatility_12w" \
  -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/regime

Get current regime classification (stable, rising, falling, volatile, shocked).

curl "https://fueldatalab.com/api/v1/regime?series_id=UUID" -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/stress

Get stress score (0-100) with component breakdown.

curl "https://fueldatalab.com/api/v1/stress?series_id=UUID" -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/shape

Get detected price movement pattern (trend, spike, oscillation, etc.).

curl "https://fueldatalab.com/api/v1/shape?series_id=UUID" -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/surprise

Get surprise score for unexpected price moves (z-score of prediction error).

Events

Price shocks and regime changes

GET

/api/v1/events

Query shock and regime change events.

Parameters: product,geo_type,since (date),event_type (shock_up, shock_down, regime_change),severity (low, med, high),limit

curl "https://fueldatalab.com/api/v1/events?product=diesel&severity=high&limit=20" \
  -H "Authorization: Bearer YOUR_KEY"

shock_up

Upward price spike (≥2σ)

shock_down

Downward price drop (≥2σ)

regime_change

Market state transition

Regional Analysis

Spreads and coherence between regions

GET

/api/v1/spreads

Get spread (price difference) between two series.

Parameters: product,left_series_id,right_series_id,period

curl "https://fueldatalab.com/api/v1/spreads?product=diesel&left_series_id=UUID1&right_series_id=UUID2" \
  -H "Authorization: Bearer YOUR_KEY"

GET

/api/v1/coherence

Get regional coherence — how synchronized are prices across regions?

>85%

High — All regions moving together

60-85%

Moderate — Some divergence

<60%

Low — Fragmented market

Pattern Analysis

Historical analogs and pattern matching

GET

/api/v1/analogs

Find historical periods with similar price patterns. Returns top 5 matches with similarity scores and what happened next.

Parameters: series_id (required),period,limit

curl "https://fueldatalab.com/api/v1/analogs?series_id=UUID" -H "Authorization: Bearer YOUR_KEY"

similarity_score

0-1 score based on normalized pattern distance

what_happened_next

Description of subsequent price movement

outcome_4w

Price change 4 weeks after analog period

outcome_12w

Price change 12 weeks after analog period

Scenarios & Simulations

What-if analysis and cost projections

POST

/api/v1/scenarios/run

Run a price scenario projection.

curl -X POST "https://fueldatalab.com/api/v1/scenarios/run" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"series_id":"UUID","type":"trend","duration_weeks":12}'

flat

Price stays constant

trend

Continue current trend

mean_reversion

Revert toward 5-year mean

shock

Apply volatility shock

POST

/api/v1/simulations/run

Simulate fuel costs with configurable parameters.

curl -X POST "https://fueldatalab.com/api/v1/simulations/run" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"series_id":"UUID","miles":10000,"mpg":6.5,"duration_weeks":12}'

Data Schemas

Available Metrics

delta_1wWeek-over-week price change

delta_4w4-week price change

delta_12w12-week price change

volatility_12wStandard deviation (12 weeks)

percentile_5yPrice percentile vs 5-year history

zscore_spot_vs_5yZ-score vs 5-year mean

Price Shapes

linear_trend_up

linear_trend_down

spike_decay

oscillation

plateau

Regime Classifications

stable

rising

falling

volatile

shocked

mean_reverting

Stress Score (0-100)

volatility

30% weight

surprise

25% weight

regime

25% weight

momentum

20% weight

80-100: SEVERE

60-79: ELEVATED

40-59: MODERATE

20-39: LOW

0-19: CALM

Ready to integrate?

Get your API key and start building.

Get API Access Try Data Lab