# 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.
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:
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 oil price that is returned. There are 11 possible types:
- BRENT_CRUDE_USD - Brent USD per barrel
- WTI_USD - West Texas Intermediate USD per barrel
- GOLD_USD - USD per ounce
- NATURAL_GAS_USD - Henry Hub USD per MMBtu
- NATURAL_GAS_GBP - GBp/thm
- GBP_USD $/GBP
- VLSFO_G20PORT_USD USD/mt
- VLSFO_GLOBALAVG_USD USD/mt
- VLSFO_AMERICAS_USD USD/mt
- VLSFO_APAC_USD USD/mt
- VLSFO_EMEA_USD USD/mt
Example of how to use the by_code parameter:
https://api.oilpriceapi.com/v1/prices/latest/?by_code=WTI_USD
The above example will return the latest WTI 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))
# 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:
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"
},
...
]
}
}