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 — all include full endpoint access:

Integrator$19/mo · 10K units

30 req/min · Best for prototyping

Analyst$49/mo · 50K units

60 req/min · Historical exports · EIA-published datasets (attributed)

Platform$149/mo · 200K units

120 req/min · High-volume production

1 unit = 1 row of data returned. 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"
}

Typical Workflow

How to use the API step by step

Get the series UUID

Call /api/v1/series with product and geo_type to get the id (UUID)

Use the UUID for data

Pass series_id to /prices, /metrics, /regime, etc.

Cache the UUID

Series UUIDs are stable — cache them to avoid repeated catalog lookups

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. Returns the id (UUID) needed for other endpoints.

Parameters:productgeo_typegeo_codecanonical=1

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

Getting the series_id: Use canonical=1 to get the primary series for a product/region. The response includes an id field — this is the series_id UUID you'll use in all other API calls.

// Response includes the UUID:
{
  "id": "a1b2c3d4-...",  // <- Use this as series_id
  "product": "diesel",
  "geo_type": "national",
  ...
}

Price Data

Historical and current prices

GET

/api/v1/prices/latest

Get the most recent price for a product/region.

Parameters:productgeo_typegeo_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*startendlimit

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.

GET

/api/v1/raw

Analyst+

Get EIA-published datasets (attributed). Requires Analyst or Platform plan.

Parameters:series_id*start_dateend_datelimit (max 5000)

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

Data Attribution: Response includes EIA attribution metadata. Source data is from the U.S. Energy Information Administration (eia.gov) and is public domain.

Signals & Metrics

Computed analytics and indicators

GET

/api/v1/metrics

Get computed metrics (deltas, volatility, percentiles).

Parameters:series_id*periodmetrics

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

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

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*periodlimit

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