Excel Add-in (Preview)
Latest energy prices in your spreadsheet as refreshable formulas:
=OILPRICE.PRICE("BRENT_CRUDE_USD")
The add-in is in preview. It is not listed in Microsoft AppSource — it installs by uploading a manifest file (sideloading), and setup takes about 2 minutes. You need an OilPriceAPI account and your API key (Dashboard → API Keys).
Platform status
| Platform | Status |
|---|---|
| Excel for Mac | Verified — Excel for Mac 16.110.2 on macOS passed the recorded preview runtime smoke on 2026-07-03: sideload, key save/test, PRICE, GET, cell-reference recalculation, and diagnostics. |
| Excel on the web | Unverified — an install path exists (below) but no runtime smoke is recorded for it yet. |
| Excel desktop on Windows | Unverified — install paths exist (below) but no runtime smoke is recorded for them yet. |
Only Mac has a recorded receipt. This table is updated as each platform's runtime smoke is recorded — until then, treat the web and Windows paths as at-your-own-risk preview.
Install — Excel desktop on Mac (verified)
One line in Terminal, then restart Excel:
mkdir -p ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef && curl -fsSL https://oilpriceapi.github.io/excel-energy-addin/manifest.xml -o ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/oilprice-manifest.xml
Then Insert → My Add-ins → OilPrice (under Developer Add-ins). Open the OilPrice pane, paste your API key, Save Key, then Test Key.
Install — Excel on the web (unverified)
- Download the add-in file: manifest.xml (right-click → Save link as… if it opens in the browser).
- Open your workbook in Excel at office.com.
- Home tab → Add-ins → More Add-ins.
- My Add-ins tab → Upload My Add-in (top-left of the dialog).
- Select the downloaded
manifest.xml→ Upload. - Click the OilPrice ribbon button, paste your API key, Save Key, then Test Key.
Install — Excel desktop on Windows (unverified)
If your company uses Microsoft 365 (simplest — no scripts):
admin.microsoft.com → Settings → Integrated apps → Upload custom apps.
App type Office Add-in → Provide link to manifest file:
https://oilpriceapi.github.io/excel-energy-addin/manifest.xmlAssign to yourself (or your team), finish, and restart Excel. The add-in appears automatically (allow up to a few hours the first time).
Personal machine with admin rights: download and double-click install-windows.cmd, approve the administrator prompt, restart Excel, then Insert → My Add-ins → Shared Folder → OilPrice. Desktop Excel on Windows cannot load the hosted manifest URL directly — it sideloads from a trusted local/shared catalog, which is what the script sets up.
Formulas
| Formula | Returns |
|---|---|
=OILPRICE.PRICE("BRENT_CRUDE_USD") | Latest price as a bare number |
=OILPRICE.PRICE(A1) | Price for the code in cell A1 — recalculates when A1 changes |
=OILPRICE.INFO("NATURAL_GAS_GBP") | Spilled Field/Value table: price, currency, unit, source, timestamps, freshness |
=OILPRICE.STATUS("BALTIC_CAPESIZE_INDEX") | Freshness of the latest quote: current, stale, or another API-reported status |
=OILPRICE.UNIT("NATURAL_GAS_GBP") | Currency/unit of the quote, e.g. GBp/therm or USD/barrel |
=OILPRICE.GET("/v1/prices/latest", "by_code=DIESEL_USD") | A supported API endpoint (see the allowlist below), spilled into cells |
=OILPRICE.CODES() | Commodity code table (shorthand for GET on /v1/commodities) |
Commodity codes match the API — see the full commodity list for what your plan includes.
OILPRICE.INFO
PRICE deliberately returns a bare number so it charts and aggregates. INFO is its companion: a two-column Field/Value table with code, price, currency, unit, formatted, source, source_description, as_of, collected_at, data_status, stale, and age_days — everything needed to interpret the number. A value like NATURAL_GAS_GBP = 142.19 is pence per therm, not USD; INFO (or UNIT) is how you know.
OILPRICE.STATUS
Returns the API's freshness verdict for the latest quote — current, stale, or another API-reported status — so stale data is distinguishable from fresh in the worksheet. Data cadence varies by source, market hours, and dataset; refresh timing follows Excel recalculation.
OILPRICE.GET supported endpoints
OILPRICE.GET is allowlisted, not open: it accepts only the GET endpoints below. Any other path returns #UNSUPPORTED_ENDPOINT in the cell. The file of record is ENDPOINT_CATALOG in the add-in source.
| Endpoint | Allowed paths |
|---|---|
| API status | /v1/status |
| Prices | /v1/prices, /v1/prices/latest, /v1/prices/past_day, /v1/prices/past_week, /v1/prices/past_month, /v1/prices/past_year, /v1/prices/historical, /v1/prices/all, /v1/prices/all/health |
| Diesel prices | /v1/diesel-prices |
| Rig counts | /v1/rig-counts + /latest, /current, /historical, /trends, /summary |
| Storage | /v1/storage + /cushing, /spr, /regional, /history/{code} |
| EIA oil inventories | /v1/ei/oil_inventories + /latest, /summary, /by_product, /historical, /cushing, /{series} |
| OPEC production | /v1/ei/opec_productions + /latest, /total, /by_country, /historical, /top_producers, /{country} |
| Bunker fuels | /v1/bunker-fuels/all, /compare, /spreads/ports, /ports/{LOCODE}, /historical/{LOCODE} |
| Well production | /v1/well-production/summary, /states, /states/{XX}, /pru/{id}, /wells/{id}, /top-producers, /cycle-time, /cycle-time/cohorts |
| Well permits | /v1/ei/well-permits + /preview, /states, /states/{XX}, /latest, /summary, /by-state, /by-operator, /by-formation, /search, /{id} |
| Drilling intelligence | /v1/drilling-intelligence + /latest, /summary, /trends, /frac-spreads, /well-permits, /duc-wells, /completions, /wells-drilled, /basin/{name} |
| Analytics | /v1/analytics/performance, /statistics, /correlation, /trend, /spread, /forecast |
| Futures | /v1/futures/{family} for ice-brent, ice-wti, ice-gasoil, natural-gas, eua-carbon — each optionally + /historical, /ohlc, /intraday, /spreads, /curve, /spread-history |
| Commodity catalog | /v1/commodities, /v1/commodities/categories, /v1/commodities/{code} |
Notes that matter in practice:
- Your plan still applies. The allowlist is what the add-in will call, not what your key is entitled to — an endpoint outside your plan returns
#UPGRADE_REQUIREDin the cell. - Never put credentials in the query string. A query containing key-like parameters (
api_key,token,secret, …) is refused with#UNSUPPORTED_QUERY. The add-in sends your saved key in the request header. past_week/past_monthtruncation. These endpoints return only the ~100 most recent intraday ticks (about a day). When that cap is hit the spilled table ends with aTRUNCATED:note row steering you to/v1/prices/historicalwithstart_date/end_datefor the full range.- Nested API fields spill as dot-named columns (e.g.
port.code), so values stay usable in formulas and charts rather than appearing as JSON blobs.
Errors and recovery
Formula errors are plain worksheet strings (#CODE: message), never silent zeros. PRICE, STATUS, and UNIT return the error in the cell; GET and INFO return it as a one-row table.
| Cell error | Meaning | What to do |
|---|---|---|
#AUTH_REQUIRED | No key saved for formulas | Open the OilPrice pane and save your key |
#AUTH_INVALID | Key invalid or expired | Replace the key in the OilPrice pane |
#UPGRADE_REQUIRED | Quota reached, or the endpoint is outside your plan | Review your plan on the pricing page |
#API_ACCESS_SUSPENDED | Account suspended | Contact support — do not rotate the key or assume an upgrade restores access |
#EMAIL_CONFIRMATION_REQUIRED | Email not confirmed | Use the confirmation link shown in the error |
#ACCESS_DENIED | 403 for a reason the add-in could not verify | Run Test Key, then contact support if it persists |
#RATE_LIMITED | Rate limit hit | The error includes the retry time (from Retry-After / X-RateLimit-Reset) — wait, then retry |
#INVALID_CODE | Bad commodity code or request parameter | Check the code — the message often suggests the right one |
#NO_DATA | API returned no matching data | Check the commodity code or query |
#UNSUPPORTED_ENDPOINT | Path not on the GET allowlist above | Use a supported endpoint |
#UNSUPPORTED_QUERY | Credential-like key in the query string | Remove it — the saved key is sent automatically |
#TIMEOUT | No response within 15 seconds | Retry, then use Test Key after checking service status |
#OFFLINE | This device appears to be offline | Reconnect, then retry |
#NETWORK_OR_CORS | Browser or CORS policy blocked the request | Copy diagnostics and contact support — don't replace the key unless the pane says AUTH_INVALID |
#SERVER_ERROR / #INVALID_RESPONSE | API unavailable or returned an unreadable response | Retry once, then copy diagnostics and contact support |
#NAME? | Excel did not load the custom functions | Close Excel fully and reopen; on the web, remove and re-upload the manifest |
Diagnostics
The OilPrice task pane has a Diagnostics section showing add-in version, Excel host, runtime support, network state, storage state, and the last request (result, HTTP status, duration, and request ID). Copy Diagnostics puts a support-ready summary on the clipboard — API keys are never stored in diagnostics or copied. When you email support@oilpriceapi.com, include the exact cell error text plus the copied diagnostics; never include your API key.
Starter workbook
A self-service starter workbook and no-manifest onboarding are planned — scope is tracked in website-clean#604.
Source
The add-in is open source: OilpriceAPI/excel-energy-addin — issues and feature requests welcome.