Data Freshness & Update Frequency

Understanding when and how data updates is critical for building reliable integrations. This guide explains update frequencies, timestamp behavior, and how to detect stale data.

Overview

• All timestamps are UTC in ISO 8601 format (e.g., 2026-02-02T14:35:00Z)
• Update frequency varies by commodity type and data source
• Timestamps update on every refresh cycle, even if the price hasn't changed

Timestamp Behavior

Does the timestamp update when the price doesn't change?

Yes. The created_at timestamp reflects when data was last refreshed, not when the price last changed. This is intentional - it lets you verify the API is actively polling data sources.

Example Response:

{
  "code": "BRENT_CRUDE",
  "price": 76.42,
  "currency": "USD",
  "unit": "barrel",
  "created_at": "2026-02-02T14:35:00Z"
}

The created_at timestamp means "this price was confirmed accurate at 14:35 UTC" - not "the price changed at 14:35."

How to detect actual price changes

To detect when prices actually change, you have several options:

1. Compare consecutive price values in your application
2. Use webhooks - only triggered on actual price changes
3. Check the change_24h field in analytics endpoints for price movement

Update Frequency by Category

High-Frequency Data (5-15 minute updates)

Daily Data (1x per day)

Weekly Data

Monthly Data

Detecting Stale Data

Freshness Thresholds

Use these guidelines to determine if data might be stale:

Checking Freshness in Code

from datetime import datetime, timedelta, timezone

def is_stale(created_at_str, max_age_minutes):
    """Check if data is stale based on timestamp."""
    created_at = datetime.fromisoformat(created_at_str.replace('Z', '+00:00'))
    age = datetime.now(timezone.utc) - created_at
    return age > timedelta(minutes=max_age_minutes)

# Example: Check if crude oil data is stale (>15 min old)
if is_stale(response['created_at'], max_age_minutes=15):
    print("Warning: Data may be stale")

Weekend and Holiday Behavior

• Weekends: Futures markets are closed. Expect no updates from Saturday to Sunday.
• US Holidays: US-sourced data (EIA) may be delayed by 1-2 days.
• UK Holidays: UK gas data may show last known price.
• Market Holidays: Exchange-specific holidays affect futures data.

Response Headers for Freshness

Every API response includes headers to help monitor data currency:

Handling Missing or Delayed Data

Why data might be missing

1. Source outage: Data provider experiencing issues
2. Market closed: No trading activity (weekends, holidays)
3. Network issues: Temporary connectivity problems

What we do automatically

• Failover: If primary source fails, backup sources activate within 5 minutes
• Monitoring: Our team is alerted to source issues 24/7
• Carry-forward: For some daily commodities, last known price is preserved with original timestamp

What you should do

1. Check timestamps: Always verify created_at is recent enough for your use case
2. Handle nulls: Missing data returns null - your code should handle this gracefully
3. Use fallbacks: Consider caching recent prices as a fallback
4. Subscribe to status: Follow @oilpricehourly for service updates

API Endpoints for Freshness Monitoring

Check Latest Timestamp

GET /v1/prices/latest?by_code=BRENT_CRUDE

The created_at field in the response shows when data was last refreshed.

Bulk Freshness Check

GET /v1/prices/latest

Returns latest prices for all commodities - useful for monitoring freshness across your portfolio.

Contact

For questions about data freshness or to report stale data:

• Email: [email protected]
• Response Time: Same business day for freshness concerns