OilPriceAPI Node.js SDK

Official Node.js and TypeScript client for source-timestamped OilPriceAPI energy data. It provides typed resources, bounded retries, explicit errors, raw response access, and executable example manifests.

Mutable offer, catalog, freshness, entitlement, and data-rights wording is governed by the reviewed product-facts.json contract. Latest available values include source timestamps; cadence, history depth, and access vary by source, market hours, dataset, and account entitlement.

Install

npm install oilpriceapi

The SDK requires Node.js 18 or newer. An installed resource helper does not imply that every dataset or workflow is enabled for an account; confirm access in the current API response and documentation.

Authenticate

Create an API key in the OilPriceAPI dashboard and provide it through the environment. Do not put a key in source code, a URL, logs, screenshots, generated artifacts, or issue text.

export OILPRICEAPI_KEY="your-key-from-the-dashboard"

The API authentication header is Authorization: Token YOUR_API_KEY.

First Request With Source Context

The canonical first request is GET /v1/prices/latest?by_code=BRENT_CRUDE_USD. This TypeScript example fails closed if the response omits the context needed to interpret the value:

import{OilPriceAPI}from"oilpriceapi";constclient=newOilPriceAPI({apiKey: process.env.OILPRICEAPI_KEY,retries: 0,timeout: 30_000,});const[record]=awaitclient.getLatestPrices({commodity: "BRENT_CRUDE_USD",});consttimestampFields=["as_of","source_timestamp","created_at","updated_at",]asconst;consttimestampField=timestampFields.find((field)=>typeofrecord?.[field]==="string"&&record[field].trim(),);if(!record||!Number.isFinite(record.price)||typeofrecord.code!=="string"||typeofrecord.currency!=="string"||typeofrecord.unit!=="string"||typeofrecord.source!=="string"||!timestampField){thrownewError("MALFORMED_RESPONSE: source context is incomplete");}console.log({code: record.code,price: record.price,currency: record.currency,unit: record.unit,source: record.source,apiTimestampField: timestampField,apiTimestamp: record[timestampField],freshness: record.data_status,});

The reviewed standalone form is examples/snippets/latest-price.ts. CI type-checks and executes it against production-shaped fixtures, then publishes its exact code and checksum in the release snippet manifest.

Several Prices In One Request

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.

constprices=awaitclient.getLatestPrices({commodity: "BRENT_CRUDE_USD,WTI_USD,NATURAL_GAS_USD",});for(constpofprices){console.log(p.code,p.price,p.currency);}

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.

Permit To Production

Well-level production coverage is narrower than permit coverage. Check the live coverage response before following a permit into monthly production history:

constsummary=awaitclient.wellProduction.summary();if(!summary.coverage){thrownewError("MALFORMED_RESPONSE: well-production coverage is missing");}constcoveredStates=newSet(summary.coverage.well_level_states_with_data??[]);constpermits=awaitclient.ei.wellPermits.searchLatest({states: "TX",well_name: "Eagle",});for(constpermitofpermits){if(!coveredStates.has(permit.state_code)||!/^\d{14}$/.test(permit.api_number??"")){continue;}constproduction=awaitclient.wellProduction.wellDetail(permit.api_number!);console.log(permit.well.name,production.data);}

An empty search or history is a valid data state. Do not infer nationwide well-level coverage from the presence of permit data or an SDK method.

CommonJS

const{ OilPriceAPI }=require("oilpriceapi");constclient=newOilPriceAPI({apiKey: process.env.OILPRICEAPI_KEY});const[price]=awaitclient.getLatestPrices({commodity: "BRENT_CRUDE_USD",});console.log(price.code,price.price,price.currency,price.unit,price.created_at);

Recovery

The package exposes typed errors for customer-recoverable boundaries:

import{AuthenticationError,OilPriceAPI,OilPriceAPIError,RateLimitError,TimeoutError,isEntitlementError,isQuotaError,}from"oilpriceapi";constclient=newOilPriceAPI({apiKey: process.env.OILPRICEAPI_KEY});try{awaitclient.getLatestPrices({commodity: "BRENT_CRUDE_USD"});}catch(error){if(errorinstanceofAuthenticationError){console.error("Replace the missing, expired, or revoked API key.");}elseif(errorinstanceofRateLimitError){console.error("Wait for the API-provided reset window.");}elseif(errorinstanceofTimeoutError){console.error("Retry once, then check https://status.oilpriceapi.com.");}elseif(isQuotaError(error)){console.error(`Request quota exhausted; ${error.remediationUrl??"follow the API-provided recovery details"}.`,);}elseif(isEntitlementError(error)){console.error(`This dataset needs the ${error.requiredPlan??"required"} plan.`);}elseif(errorinstanceofOilPriceAPIError){console.error(error.requestId ? `Request ID: ${error.requestId}` : "Unexpected API error.");}else{throwerror;}}

Executable recovery examples cover 401, 403, 429, and timeout responses under examples/snippets/. Empty or malformed successful responses should stop processing rather than inventing a price, unit, currency, source, or timestamp.

All HTTP failures expose statusCode, code, requestId, recovery links and plan metadata when the API supplies them. rawBody and headers are retained for diagnostics; the configured API key is redacted before either is exposed.

Capabilities

The client includes resources for latest and historical values plus additional dataset and workflow families. Availability is determined by the live API and account entitlement, not by the presence of a method or exported type.

• Use API documentation for current paths and parameters.
• Use the commodity catalog to inspect codes.
• Use pricing to review current account options.
• Use the data usage policy before redistributing data.

Standard plans provide API access, normalization, monitoring, and delivery; they do not transfer ownership of underlying source data or unrestricted raw data redistribution rights.

Raw Responses

client.raw returns response data together with HTTP status and response headers when the application needs request IDs, rate-limit metadata, or an unwrapped payload. Do not log authorization headers or mutable account data.

constresponse=awaitclient.raw.getLatestPrices({commodity: "BRENT_CRUDE_USD",});console.log(response.status,response.headers.get("x-request-id"),response.data);

Reproducible Examples

Website and documentation snippets are maintained in examples/snippets/. Every release attaches a versioned manifest containing the package version, minimum runtime, source commit, expected response shape, exact code, and SHA-256 for each example.

npm run snippets:check
npm run snippets:build -- --source-commit "$(git rev-parse HEAD)"

Development

npm ci
npm run storefront:check
npm run check:secrets
npm run lint
npm test
npm run build
npm pack --dry-run

Live tests require an explicitly supplied non-customer test credential. Unit and snippet tests use local fixtures and do not print or persist credentials.

Support

• API documentation
• Service status
• Product facts
• GitHub issues

Licensed under the MIT License.