Guide

Introduction

The OilpriceAPI is a RESTful (opens new window) API providing various endpoints and parameters for retrieving historical or live oil prices.

Authentication

The OilpriceAPI uses API tokens to authenticate requests. You can view and manage your API token in the OilpriceAPI Dashboard (opens new window).

Requests made with your API token count towards your account request limit, so be sure to keep it private.

All timestamps in this guide are in UTC.

• System Time: All system logs are recorded in Coordinated Universal Time (UTC).
• Timestamp Format: YYYY-MM-DDThh:mm:ssZ (e.g., 2024-10-23T14:00:00Z). ISO-8601
• Note: Ensure any time conversions account for Daylight Saving Time where applicable.

**NOTE: Make sure to include Token - NOT Bearer **

To make an authenticated request your API token should be passed in your request's Authorization header. For example in a cURL (opens new window) request it can be passed like so:

**NOTE: Make sure to include Token - NOT Bearer **

curl https://api.oilpriceapi.com/v1/prices/latest \
-H 'Authorization: Token YOUR_API_KEY' \
-H 'Content-Type: application/json'

Errors

OilpriceAPI uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, your API token has expired, etc.). Codes in the 5xx range indicate an error with OilpriceAPI's servers.

Pagination

All endpoints except for latest return a paginated list of prices. Each page is limited to 100 results.

In the response headers of each request you will find some pagination information, this includes the total number of records that can be retrieved, a link to the previous/next page and the per-page limit. For example a request's headers may include:

total: 100000,
per-page: 100,
link: <http://api.oilpriceapi.com/v1/prices?page=1000>; rel="last", <http://api.oilpriceapi.com/v1/prices?page=2>; rel="next"

In this example there are 100,000 possible data points to retrieve with 100 returned on each page. To retrieve all the results one would need to create a loop to iterate over 1000 (100,000/100) pages, passing a page=n param with each iteration.

Parameters

The OilpriceAPI includes a number of parameters that can be included in the request URL to refine the returned data.

by_type

(default: spot_price)

The by_type parameter specifies the type of price that is returned. There are two possible types:

• spot_price
• daily_average_price

Example of how to use the by_type parameter:

https://api.oilpriceapi.com/v1/prices/past_week/?by_type=daily_average_price

The above example will return the daily average prices available within the last 7 days.

by_code

(default: BRENT_CRUDE_USD)

The by_code parameter specifies the type of commodity price that is returned. There are multiple possible types:

Measure	Currency	Energy Unit	Description
BRENT_CRUDE_USD	USD	barrel	North Sea Brent Crude Oil. A light sweet crude oil and major benchmark for oil prices worldwide. Extracted from the North Sea, it's used to price two-thirds of internationally traded crude oil supplies.
DUBAI_CRUDE_USD	USD	barrel	Dubai Crude Oil (Platts). A medium sour crude oil used as a benchmark for Persian Gulf oil exports to Asia. It's one of the few Persian Gulf crude oils available on the spot market.
WTI_USD or WTI_CRUDE_USD	USD	barrel	West Texas Intermediate Crude Oil. A light sweet crude oil, serving as a major benchmark for oil pricing in the Americas. Primarily extracted in Texas and Oklahoma, it's the underlying commodity of NYMEX's oil futures contracts.
NATURAL_GAS_USD	USD	mmbtu	Henry Hub Natural Gas. The primary benchmark for North American natural gas markets. Named after the distribution hub in Louisiana, it's used as the delivery point for NYMEX natural gas futures contracts.
NATURAL_GAS_GBP	GBP	therm	UK Natural Gas NBP. The National Balancing Point (NBP) is a virtual trading location for UK natural gas. It's the most liquid gas trading point in Europe and serves as a major price benchmark.
DUTCH_TTF_EUR	EUR	mwh	Dutch Title Transfer Facility Natural Gas. The most liquid gas trading hub in continental Europe. TTF is a virtual marketplace for natural gas trading and serves as a key benchmark for European gas prices.
COAL_USD	USD	metric_ton	API2 CIF ARA Coal. A key benchmark for coal imported into northwest Europe. ARA refers to Amsterdam-Rotterdam-Antwerp, the main coal importing ports. API2 is the price assessment for coal delivered to these ports.
GOLD_USD	USD	troy_ounce	Gold Spot Price. Represents the current price for immediate delivery of gold. Gold is considered a safe-haven asset and hedge against inflation. It's widely used in jewelry, electronics, and as a store of value.
GBP_USD	USD	currency_pair	British Pound to US Dollar Exchange Rate. Often called "Cable," this pair reflects the relative value of the UK and US economies. It's one of the oldest currency pairs in the forex market.
EUR_USD	USD	currency_pair	Euro to US Dollar Exchange Rate. The world's most traded currency pair, representing the world's two largest economies. It's often referred to as "Fiber" in forex trading circles.

Example of how to use the by_code parameter:

https://api.oilpriceapi.com/v1/prices/latest/?by_code=WTI_CRUDE_USD

The above example will return the latest WTI crude oil price.

by_period

The by_period parameter gives you finer control over the period of time in which to fetch oil prices from. It can only be used with the /prices endpoint.

The by_period parameter requires two inputs, a from and to timestamp.

So for example, in Javascript the by_period parameter could be used like so:

let from = (new Date("2019-12-20")).getTime() / 1000 # convert to seconds since epoch
let to = (new Date("2020-01-20")).getTime() / 1000

let url = `https://api.oilpriceapi.com/v1/prices?by_period[from]=${from}&by_period[to]=${to}`

const headers = {
  'Authorization': 'Token YOUR_API_TOKEN',
  'Content-Type': 'application/json'
}

fetch(url, { headers })
  .then(response => response.json())
  .then(prices => console.log(prices))

Note tht the cURL equivalent requires us to URL encode the brackets and the timestamps - so something like:

curl -X GET "https://api.oilpriceapi.com/v1/prices?by_code=WTI_USD&by_period%5Bfrom%5D=1698192000&by_period%5Bto%5D=1700179199" \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json"

Endpoints

All end points can be called using the following base url:

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

So as an example, to access the latest oil price the full request URL would be:

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

The endpoint being - /latest

Below is a list of all available endpoints:

• latest
• past_day
• past_week
• past_month
• past_year

The default oil price code is BRENT_CRUDE_USD which returns the relevant Brent Crude prices, depending on the endpoint used. For WTI prices you can pass the parameter by_code=WTI_USD with the endpoint. For example:

https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD

prices/latest

This endpoint returns the latest available oil price.

Example cURL request:

curl https://api.oilpriceapi.com/v1/prices/latest \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'Content-Type: application/json'

Note YOUR_API_TOKEN needs to be replaced with your own API token.

Example response:

{
    "status": "success",
    "data": {
        "price": 80.29,
        "formatted": "$80.29",
        "currency": "USD",
        "code": "BRENT_CRUDE_USD",
        "type": "spot_price",
        "created_at": "2018-10-17T20:14:05.698Z"
    }
}

prices

This endpoint returns all oil price data available.

Example cURL request:

curl https://api.oilpriceapi.com/v1/prices \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'Content-Type: application/json'

Note YOUR_API_TOKEN needs to be replaced with your own API token.

Example response:

{
    "status": "success",
    "data": {
        "prices": [
            {
                "price": 82.73,
                "formatted": "$82.73",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:39:05.283Z"
            },
            {
                "price": 82.71,
                "formatted": "$82.71",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:40:09.823Z"
            },
            {
                "price": 82.46,
                "formatted": "$82.46",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:41:05.961Z"
            },
            ...
        ]
    }
}

prices/past_day

This endpoint returns all oil price data available within the last 24 hours.

Example cURL request:

curl https://api.oilpriceapi.com/v1/prices/past_day \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'Content-Type: application/json'

Note YOUR_API_TOKEN needs to be replaced with your own API token.

Example response:

{
    "status": "success",
    "data": {
        "prices": [
            {
                "price": 82.73,
                "formatted": "$82.73",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:39:05.283Z"
            },
            {
                "price": 82.71,
                "formatted": "$82.71",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:40:09.823Z"
            },
            {
                "price": 82.46,
                "formatted": "$82.46",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:41:05.961Z"
            },
            ...
        ]
    }
}

prices/past_week

This endpoint returns all oil price data available within the last 7 days.

Example cURL request:

curl https://api.oilpriceapi.com/v1/prices/past_week \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'Content-Type: application/json'

Note YOUR_API_TOKEN needs to be replaced with your own API token.

Example response:

{
    "status": "success",
    "data": {
        "prices": [
            {
                "price": 82.73,
                "formatted": "$82.73",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:39:05.283Z"
            },
            {
                "price": 82.71,
                "formatted": "$82.71",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:40:09.823Z"
            },
            {
                "price": 82.46,
                "formatted": "$82.46",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:41:05.961Z"
            },
            ...
        ]
    }
}

prices/past_month

This endpoint returns all oil price data available within the last 30 days.

Example cURL request:

curl https://api.oilpriceapi.com/v1/prices/past_month \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'Content-Type: application/json'

Note YOUR_API_TOKEN needs to be replaced with your own API token.

Example response:

{
    "status": "success",
    "data": {
        "prices": [
            {
                "price": 82.73,
                "formatted": "$82.73",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:39:05.283Z"
            },
            {
                "price": 82.71,
                "formatted": "$82.71",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:40:09.823Z"
            },
            {
                "price": 82.46,
                "formatted": "$82.46",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:41:05.961Z"
            },
            ...
        ]
    }
}

prices/past_year

This endpoint returns all oil price data available within the last 365 days.

Example cURL request:

curl https://api.oilpriceapi.com/v1/prices/past_year \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'Content-Type: application/json'

Note YOUR_API_TOKEN needs to be replaced with your own API token.

Example response:

{
    "status": "success",
    "data": {
        "prices": [
            {
                "price": 82.73,
                "formatted": "$82.73",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:39:05.283Z"
            },
            {
                "price": 82.71,
                "formatted": "$82.71",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:40:09.823Z"
            },
            {
                "price": 82.46,
                "formatted": "$82.46",
                "currency": "USD",
                "code": "BRENT_CRUDE_USD",
                "type": "spot_price",
                "created_at": "2018-10-10T20:41:05.961Z"
            },
            ...
        ]
    }
}