Making Requests

Learn how to make effective API requests to retrieve oil and energy price data.

Base URL

All API requests should be made to:

https://api.oilpriceapi.com/v1/

Request Format

HTTP Methods

OilPriceAPI primarily uses GET requests for data retrieval:

  • GET - Retrieve price data, commodity information, and lists

Required Headers

Every request must include:

Authorization: Token YOUR_API_KEY
Content-Type: application/json

⚠️ Common Mistakes

Authentication Header Format

The documented and recommended scheme is Token:

Authorization: Token YOUR_API_KEY

Note: Token is the recommended scheme and the one used throughout these docs. Authorization: Bearer YOUR_API_KEY is also currently accepted if you're coming from an OAuth2 background, but prefer Token for consistency.

Endpoint Format

WRONG ❌

GET /v1/prices/WTI_USD

CORRECT ✅

GET /v1/prices/latest?by_code=WTI_USD

Note: Commodity codes go in the by_code query parameter, not in the URL path.

Common Parameters

Commodity Selection

Use the by_code parameter to specify commodities:

# Single commodity
GET /v1/prices/latest?by_code=WTI_USD

# Multiple commodities (comma-separated)
GET /v1/prices/latest?by_code=WTI_USD,BRENT_CRUDE_USD,NATURAL_GAS_USD

Date Ranges

For historical data, pass a date range to the historical endpoint:

# Date range
GET /v1/prices/historical?start_date=2025-01-01&end_date=2025-01-10&by_code=WTI_USD

Date format: YYYY-MM-DD

Example Requests

Get Latest Prices

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Get Multiple Commodities

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD,BRENT_CRUDE_USD,NATURAL_GAS_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Get Historical Data

curl "https://api.oilpriceapi.com/v1/prices/historical?start_date=2025-01-01&end_date=2025-01-10&by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Request Libraries

JavaScript (Axios)

import axios from "axios";

const apiClient = axios.create({
  baseURL: "https://api.oilpriceapi.com/v1",
  headers: {
    Authorization: `Token ${process.env.OILPRICEAPI_KEY}`,
    "Content-Type": "application/json",
  },
});

// Get latest WTI price
const getLatestWTI = async () => {
  try {
    const response = await apiClient.get("/prices/latest", {
      params: { by_code: "WTI_USD" },
    });
    return response.data;
  } catch (error) {
    console.error("API Error:", error.response?.data || error.message);
  }
};

Python (Requests)

import requests
import os

class OilPriceClient:
    def __init__(self):
        self.base_url = 'https://api.oilpriceapi.com/v1'
        self.headers = {
            'Authorization': f"Token {os.environ['OILPRICEAPI_KEY']}",
            'Content-Type': 'application/json'
        }

    def get_latest_prices(self, commodity_codes):
        params = {'by_code': ','.join(commodity_codes)}
        response = requests.get(
            f'{self.base_url}/prices/latest',
            headers=self.headers,
            params=params
        )
        response.raise_for_status()
        return response.json()

# Usage
client = OilPriceClient()
data = client.get_latest_prices(['WTI_USD', 'BRENT_CRUDE_USD'])

Ruby (Net::HTTP)

require 'net/http'
require 'json'
require 'uri'

class OilPriceClient
  BASE_URL = 'https://api.oilpriceapi.com/v1'

  def initialize(api_key)
    @api_key = api_key
  end

  def get_latest_prices(commodity_codes)
    uri = URI("#{BASE_URL}/prices/latest")
    uri.query = URI.encode_www_form(by_code: commodity_codes.join(','))

    request = Net::HTTP::Get.new(uri)
    request['Authorization'] = "Token #{@api_key}"
    request['Content-Type'] = 'application/json'

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    JSON.parse(response.body)
  end
end

# Usage
client = OilPriceClient.new(ENV['OILPRICEAPI_KEY'])
data = client.get_latest_prices(['WTI_USD', 'BRENT_CRUDE_USD'])

PHP (cURL)

<?php
class OilPriceClient {
    private $baseUrl = 'https://api.oilpriceapi.com/v1';
    private $apiKey;

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function getLatestPrices($commodityCodes) {
        $url = $this->baseUrl . '/prices/latest?' . http_build_query([
            'by_code' => implode(',', $commodityCodes)
        ]);

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Token ' . $this->apiKey,
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new Exception('API request failed with code: ' . $httpCode);
        }

        return json_decode($response, true);
    }
}

// Usage
$client = new OilPriceClient($_ENV['OILPRICEAPI_KEY']);
$data = $client->getLatestPrices(['WTI_USD', 'BRENT_CRUDE_USD']);
?>

Pagination

For endpoints returning large datasets, use pagination parameters:

# Get page 2 with 50 results per page
GET /v1/prices/historical?page=2&per_page=50&by_code=WTI_USD

Default pagination:

  • page: 1
  • per_page: 100

Read the X-Total, X-Total-Pages, and Link (RFC 5988) response headers to page through large result sets.

Filtering Commodities

GET /v1/commodities returns the full catalog. Filter it client-side by the category field on each item — the endpoint does not currently apply category, search, or active query parameters (they are ignored and the full list is returned).

import requests

resp = requests.get(
    "https://api.oilpriceapi.com/v1/commodities",
    headers={"Authorization": "Token YOUR_API_KEY"},
).json()

crude = [c for c in resp["data"] if c["category"] == "crude_oil"]

Best Practices

1. Always Specify Commodity Codes

List exactly the commodities you need with by_code:

# Good - Specific request
GET /v1/prices/latest?by_code=WTI_USD,BRENT_CRUDE_USD

# Avoid - No by_code returns only a single default commodity (BRENT_CRUDE_USD)
GET /v1/prices/latest

Note: Calling /v1/prices/latest without by_code does not return all commodities - it returns a single default commodity. To get multiple prices, pass a comma-separated list: by_code=WTI_USD,BRENT_CRUDE_USD.

2. Cache Responses

Refresh cadence varies by source and dataset. Cache responses using the returned timestamps and freshness metadata:

const cache = new Map();
const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes

async function getCachedPrice(commodity) {
  const cached = cache.get(commodity);
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return cached.data;
  }

  const data = await fetchPriceFromAPI(commodity);
  cache.set(commodity, { data, timestamp: Date.now() });
  return data;
}

3. Handle Errors Gracefully

Always implement proper error handling:

import time
import requests
from requests.exceptions import RequestException

def get_price_with_retry(commodity_code, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(
                f'https://api.oilpriceapi.com/v1/prices/latest',
                params={'by_code': commodity_code},
                headers={'Authorization': f'Token {API_KEY}'},
                timeout=10
            )
            response.raise_for_status()
            return response.json()
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

4. Monitor Rate Limits

Track your usage to avoid hitting limits:

function checkRateLimit(response) {
  const remaining = response.headers["x-ratelimit-remaining"];
  const limit = response.headers["x-ratelimit-limit"];

  if (remaining < limit * 0.1) {
    console.warn(`Low API quota: ${remaining}/${limit} requests remaining`);
  }
}

Troubleshooting

404 Not Found Error

Common Cause: Using commodity code in URL path instead of query parameter

# ❌ Wrong - Returns 404
curl "https://api.oilpriceapi.com/v1/prices/WTI_USD"

# ✅ Correct
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD"

401 Unauthorized Error

Common Cause: A missing or invalid API key. Make sure the Authorization header is present and your key is correct.

# ❌ Wrong - no Authorization header, returns 401
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD"

# ✅ Correct
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

A 401 response includes a JSON body with error.code set to UNAUTHORIZED and a request_id you can quote when contacting support.

Quick Verification Test

Test your setup with this command (replace YOUR_API_KEY):

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Expected Response:

  • Status: 200 OK
  • Body contains "code": "WTI_USD" and current price data

Still having issues? Email support@oilpriceapi.com with your request_id from the error response.

Next Steps

Learn about handling responses and parsing the returned data.

Last Updated: