The official PHP client for source-timestamped oil, gas, refined-product, futures, and related energy data from OilPriceAPI.
Create an API key | Documentation | API explorer | Pricing
- PHP 8.1 or newer
ext-curlandext-json- API base URL:
https://api.oilpriceapi.com - Auth header:
Authorization: Token YOUR_API_KEY - Environment variable used by the executable example:
OILPRICEAPI_KEY
The package has no third-party runtime dependency.
composer require oilpriceapi/oilpriceapiThe canonical authenticated first request is:
GET /v1/prices/latest?by_code=BRENT_CRUDE_USD
Run the packaged, tested example:
export OILPRICEAPI_KEY="your-api-key"
php vendor/oilpriceapi/oilpriceapi/examples/quickstart.phpThe same request in application code:
<?phprequire__DIR__ . '/vendor/autoload.php';
useOilPriceAPI\Client;
$client = newClient(); // reads OILPRICEAPI_KEY$brent = $client->latest('BRENT_CRUDE_USD');
printf(
"%s %.2f %s/%s as of %s (source: %s)\n",
$brent->code,
$brent->price,
$brent->currency,
$brent->unit ?? 'unknown',
$brent->updatedAt?->format(DATE_ATOM) ?? 'unknown',
$brent->source ?? 'unknown',
);For missing configuration and actionable 401, 403, and 429 recovery, use the
exact source in examples/quickstart.php. CI builds
a Composer ZIP, installs it into a clean project, and runs every recovery path
against fixtures.
Production returns a singleton data object for the canonical latest-price
request, so latest('BRENT_CRUDE_USD') returns one Price. The SDK retains
support for a legacy data.prices[] envelope, returned as a list, but rejects a
successful response that contains no usable price. Pass a commodity code when
the caller requires a predictable single Price result.
Price is immutable and exposes code, price, currency, updatedAt,
source, change24h, name, unit, type, and formatted when supplied by
the API.
by_code accepts up to 20 comma-separated commodity codes, and the whole call
counts as one request — not one per code. Batching is the cheapest way to make
an allowance go further: twenty codes in one call stretches it twenty times.
$prices = $client->latest('BRENT_CRUDE_USD,WTI_USD,NATURAL_GAS_USD');
foreach ($pricesas$price) {
printf("%s %.2f %s\n", $price->code, $price->price, $price->currency);
}One code returns a single Price; two or more return a list<Price> — the
return type is Price|array, so use is_array() if the count is dynamic.
Asking for more than 20 codes returns 400 Too many commodity codes requested (max: 20, requested: N). An unrecognised code also returns 400, with a "did you
mean" suggestion — so validate your code list once rather than on every poll.
For current plan allowances and the polling interval that fits them, see Rate Limiting.
The demo endpoint does not require an API key:
$client = new \OilPriceAPI\Client();
foreach ($client->demoPrices() as$price) {
printf("%s %.2f %s/%s\n",
$price->code,
$price->price,
$price->currency,
$price->unit ?? 'unknown',
);
}Demo availability and limits are returned by the endpoint. Authenticated dataset access and limits vary by plan, source, and account entitlement.
$day = $client->pastDay('BRENT_CRUDE_USD');
$week = $client->pastWeek('BRENT_CRUDE_USD');
$month = $client->pastMonth('BRENT_CRUDE_USD');
$year = $client->pastYear('BRENT_CRUDE_USD');Each method returns a list of immutable Price objects.
useOilPriceAPI\Exception\ApiException;
useOilPriceAPI\Exception\AuthenticationException;
useOilPriceAPI\Exception\RateLimitException;
try {
$brent = $client->latest('BRENT_CRUDE_USD');
} catch (AuthenticationException$error) {
error_log('Replace OILPRICEAPI_KEY with an active key.');
} catch (RateLimitException$error) {
error_log(sprintf('Retry after %d seconds.', $error->retryAfter ?? 0));
} catch (ApiException$error) {
if (in_array($error->statusCode, [402, 403], true)) {
error_log('Review dataset access at https://www.oilpriceapi.com/pricing');
} else {
error_log(sprintf('Request failed with HTTP %d.', $error->statusCode));
}
}All SDK exceptions extend ApiException. RateLimitException exposes
retryAfter and the server-reported limit when present.
The client retries 429 and 5xx responses with bounded exponential backoff
and honors Retry-After.
$client = new \OilPriceAPI\Client(
apiKey: getenv('OILPRICEAPI_KEY') ?: null,
timeout: 10.0,
maxRetries: 2,
);For tests, baseUrl, HttpTransport, and the retry sleeper are injectable.
The executable example also reads OILPRICEAPI_BASE_URL when a fixture or
private compatible endpoint is required.
Use raw() for a versioned GET route that does not yet have a typed method:
$curve = $client->raw()->get('/v1/futures/brent/curve');Availability varies by dataset, plan, source, and account entitlement. Review current access rather than relying on a plan claim copied into package metadata.
The versioned, reviewed contract is
product-facts.json. Mutable
offer, catalog, freshness, entitlement, and data-rights claims should link to
that contract instead of being duplicated in SDK documentation.
Current reviewed catalog wording: a broad catalog spanning crude oil, natural gas, refined products, futures, marine fuels, carbon markets, metals, forex, and selected energy-intelligence datasets. See the commodity catalog for current availability.
Source timestamps describe the values in each response. They do not imply one sitewide update interval: refresh cadence varies by source, market hours, dataset, and plan.
Standard plans provide API access, normalization, monitoring, and delivery; they do not grant ownership of source data or unrestricted raw-data redistribution rights. See the data usage policy.
composer validate --strict
composer install
composer test
./scripts/clean-install-smoke.shThe guarded production smoke requires OILPRICEAPI_TEST_KEY:
OILPRICEAPI_KEY="your-test-key" php examples/smoke.phpMIT licensed. See LICENSE.