Quick Start

Get up and running with OilPriceAPI in under 5 minutes.

Overview

This guide will help you:

  1. Try the no-key demo endpoint
  2. Get your API key
  3. Make your first authenticated API request
  4. Understand the response format
  5. Explore next steps

Step 0: Try the Demo Endpoint

Start with the live demo endpoint. It requires no API key and returns the same data.prices array shape used by multi-code latest-price responses:

curl -X GET "https://api.oilpriceapi.com/v1/demo/prices"

Example response:

{
  "status": "success",
  "data": {
    "prices": [
      {
        "code": "WTI_USD",
        "name": "WTI Crude Oil",
        "price": 73.64,
        "currency": "USD",
        "updated_at": "2026-07-08T18:21:13Z",
        "change_24h": 4.54,
        "source": "OilPriceAPI"
      }
    ]
  },
  "meta": {
    "demo_mode": true,
    "rate_limit": "20 requests per hour",
    "note": "This is the free demo API."
  }
}

Step 1: Get Your API Key

Sign Up

  1. Visit oilpriceapi.com/signup
  2. Create your account (free tier available)
  3. Verify your email address

The Free plan includes 50 requests per day. New accounts start with a 7-day free trial of 10,000 requests; paid plans carry quotas from 10,000 / month (Developer) to 1,000,000 / month (Scale).

Generate API Key

  1. Log into your dashboard
  2. Navigate to API Keys section
  3. Click Create New Key
  4. Give it a descriptive name (e.g., "Production App")
  5. Copy your key immediately - it won't be shown again!
**Tip**: Create separate keys for development and production environments

Step 2: Make Your First Request

Let's fetch the latest oil prices:

Step 3: Understanding the Response

Here's what you'll receive when requesting multiple commodities:

{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 68.58,
        "formatted": "$68.58",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2026-07-03T13:43:01.099Z",
        "type": "spot_price",
        "source": "market_reporting"
      },
      {
        "price": 71.98,
        "formatted": "$71.98",
        "currency": "USD",
        "code": "BRENT_CRUDE_USD",
        "created_at": "2026-07-03T13:43:01.099Z",
        "type": "spot_price",
        "source": "market_reporting"
      }
    ],
    "metadata": {
      "request_id": "6390b34903a8d3f0",
      "timestamp": "2026-07-03T13:47:37Z",
      "version": "v1"
    }
  }
}

The data.prices field is an array, so find each commodity by its code rather than indexing by name.

Key Fields Explained

FieldDescriptionExample
priceCurrent spot price74.52
formattedPrice with currency symbol$74.52
currencyPrice currency codeUSD
codeCommodity identifierWTI_USD
created_atPrice timestamp (ISO 8601)2025-12-29T15:30:00.000Z
typePrice typespot_price
sourceData source identifiermarket_reporting

Step 4: Common Use Cases

Get Specific Commodities

# Only get WTI and Natural Gas prices
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD,NATURAL_GAS_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Get Multiple Commodity Prices

# Get WTI and Brent prices together
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD,BRENT_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Get Historical Data

# Get past 24 hours of WTI data
curl "https://api.oilpriceapi.com/v1/prices/past_day?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Step 5: Best Practices

1. Store API Keys Securely

Never hardcode API keys:

// ❌ Bad
const apiKey = "YOUR_API_KEY";

// ✅ Good
const apiKey = process.env.OILPRICEAPI_KEY;

2. Handle Errors Gracefully

try {
  const response = await fetch(
    "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD,BRENT_CRUDE_USD",
    {
      headers: { Authorization: `Token ${apiKey}` },
    },
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data;
} catch (error) {
  console.error("Failed to fetch prices:", error);
  // Implement fallback logic
}

3. Implement Caching

Cache responses according to your application's tolerance and the returned freshness metadata:

import time
from functools import lru_cache

@lru_cache(maxsize=1)
def get_cached_prices(cache_key):
    response = requests.get(
        'https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD,BRENT_CRUDE_USD',
        headers={'Authorization': f'Token {API_KEY}'}
    )
    return response.json()

# Generate new cache key every 5 minutes
cache_key = int(time.time() // 300)
prices = get_cached_prices(cache_key)

Step 6: Direct API Integration

The API is simple to integrate directly into your application without any additional libraries:

Quick Examples

Price Alert System

async function checkPriceThreshold() {
  const response = await fetch(
    "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD",
    {
      headers: { Authorization: `Token ${process.env.OILPRICEAPI_KEY}` },
    },
  );

  const data = await response.json();
  // Single commodity requests return a flat data object
  const wtiPrice = data.data.price;

  if (wtiPrice > 80) {
    sendAlert(`WTI above $80: Currently $${wtiPrice}`);
  }
}

// Check every 5 minutes
setInterval(checkPriceThreshold, 5 * 60 * 1000);

Simple Dashboard

<!DOCTYPE html>
<html>
  <head>
    <title>Oil Prices</title>
  </head>
  <body>
    <h1>Live Oil Prices</h1>
    <div id="prices">Loading...</div>

    <script>
      async function updatePrices() {
        // Note: In production, proxy through your backend
        const response = await fetch("/api/prices");
        const data = await response.json();

        // data.data.prices is an array - find each commodity by its code
        const wti = data.data.prices.find((p) => p.code === "WTI_USD");
        const brent = data.data.prices.find(
          (p) => p.code === "BRENT_CRUDE_USD",
        );

        document.getElementById("prices").innerHTML = `
        <p>WTI: $${wti.price}</p>
        <p>Brent: $${brent.price}</p>
        <p>Last Updated: ${new Date(wti.created_at).toLocaleString()}</p>
      `;
      }

      updatePrices();
      // 30 minutes fits the free plan (48 requests/day). Developer and
      // above: 5 * 60 * 1000. See /guides/rate-limiting#how-often-to-poll
      setInterval(updatePrices, 30 * 60 * 1000);
    </script>
  </body>
</html>

What's Next?

Now that you've made your first request, explore:

Need Help?

Last Updated: