Developer guide

OilPriceAPI with Java

Start with one authenticated Brent request, verify the returned source timestamp, then build outward from the canonical quickstart.

Get API key Canonical quickstart

Runtime

JDK 11+ example

Environment

OILPRICEAPI_KEY

Authentication

Authorization: Token YOUR_API_KEY

First request

/v1/prices/latest?by_code=BRENT_CRUDE_USD

First request

Prove the API path first

Store the key as OILPRICEAPI_KEY and run the request from a trusted server process. Do not expose the key in browser bundles, logs, notebooks, or shared documents.

No test-key prefix

OilPriceAPI does not issue special test keys. Use the keyless demo endpoint or fixtures for tests; keep customer keys out of CI.

java

JDK 11+ example

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String apiKey = System.getenv("OILPRICEAPI_KEY");
if (apiKey == null || apiKey.isBlank()) {
    throw new IllegalStateException("OILPRICEAPI_KEY is required");
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD"))
    .header("Authorization", "Token " + apiKey)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());

This example uses java.net.http.HttpClient.

Universal curl

Compare your client with the contract

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

Expected shape

Read the timestamp from the response

{
  "status": "success",
  "data": {
    "code": "BRENT_CRUDE_USD",
    "price": 78.41,
    "currency": "USD",
    "created_at": "2026-03-09T12:00:00.000Z",
    "type": "spot_price"
  }
}

Keyless first touch

Use demo data before signup

The demo route is the supported no-key path. It is rate limited and intentionally narrower than authenticated, account-entitled access.

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

Open demo response

Recover without guessing

Result	Next action
401	Check that the header is exactly Authorization: Token YOUR_API_KEY.
402 / 403	The dataset may require a plan or account entitlement. Check pricing or contact support.
429	Read the rate-limit response and retry after the indicated reset; do not loop immediately.
Timeout / 5xx	Use a bounded timeout and exponential backoff. Keep the last valid source timestamp visible.

Current offer

7-day core commodity API trial

New accounts receive 10,000 trial requests without a credit card, followed by 200 requests per month on Free. Dataset access and limits vary by plan, source, and account entitlement.

Continue with quickstart API documentation