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

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!

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

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();
      setInterval(updatePrices, 60000); // Update every minute
    </script>
  </body>
</html>

What's Next?

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

• API Reference - All available endpoints
• Authentication Guide - Security best practices
• Making Requests - Request patterns and examples
• Handling Responses - Response parsing and error handling
• Premium Features - Advanced endpoints and features

Need Help?

• Email: support@oilpriceapi.com
• Chat: Available in dashboard
• FAQ - Common questions answered
• Status Page - API health