API documentation
US Crude Oil Imports API
Since 2009Who supplies America's crude: monthly import volumes by origin country and crude grade, from the EIA company-level import statistics (form EIA-814).
500 req/mo · No credit card required · One key, every API on the platform
- Checking status…
- Monthly since 2009
- 10 origins: world + 9 countries
- Unit: thousand barrels (monthly totals)
- Refreshed on each monthly release (~2-month lag)
Base URL & authentication
All endpoints live under one base URL. Authenticate every request with your key
in the X-Api-Key header — no OAuth, no signing. The same key works
on every API of the platform.
# Base URL {{GATEWAY_URL}} # Every request X-Api-Key: sk_live_YOUR_KEY
Missing or invalid keys return 401 — see
errors. The demo endpoint is the only keyless route.
Endpoints
All paths relative to the base URL. Every 200 ships ETag,
Cache-Control and RateLimit-* headers.
| Method | Path | Summary |
|---|---|---|
| GET | /oil-imports/latest Free+ | Latest total imports of every origin (supplier ranking) |
| GET | /oil-imports/{origin} Free+ | Latest month of imports from a single origin |
| GET | /oil-imports/{origin}/history Free+ | Paginated monthly import history for an origin |
{origin}: world | canada | mexico | saudi-arabia | venezuela | guyana | colombia | iraq | brazil | nigeria. Query grade: all | heavy-sour | heavy-sweet | light-sour | light-sweet | medium (default all). History: start/end (YYYY-MM), keyset pagination via meta.next_end (null on the last page), limit 1–100.
Sample — 200 /oil-imports/latest
{"data":[{"origin":"world","grade":"all","period":"2026-04","value":187705,"unit":"thousand barrels","source":"EIA"},{"origin":"canada","grade":"all","period":"2026-04","value":130668,"unit":"thousand barrels","source":"EIA"}],"meta":{"source":"U.S. Energy Information Administration","destination":"us"}}
Errors, auth & limits
One uniform error contract everywhere:
{ "error": { "code", "message" } } with stable,
machine-readable codes — shared by every API on the platform.
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing X-Api-Key header, or invalid/revoked key. |
| 400 | VALIDATION_ERROR | Bad query/path parameters. |
| 404 | ORIGIN_NOT_FOUND · NO_DATA · NOT_FOUND | Unknown value for the path parameter (the message lists the valid ones), no data for the requested range yet, or unknown route. |
| 429 | RATE_LIMITED | Per-minute limit of your plan exceeded — check Retry-After. |
| 429 | QUOTA_EXCEEDED | Monthly cap reached. Nothing is billed on top — resets on the 1st (UTC). |
| 502 | UPSTREAM_ERROR | The origin API was unreachable — retry shortly. |
Data provenance
The EIA company-level import statistics (form EIA-814): monthly US crude oil imports by origin country and crude grade, with history since 2009. Values are monthly totals in thousand barrels, not daily rates. This product is not endorsed by or affiliated with the EIA.
Example
curl -H "X-Api-Key: sk_live_YOUR_KEY" \ https://api.synergicapis.com/oil-imports/latest
import requests
r = requests.get(
"https://api.synergicapis.com/oil-imports/latest",
headers={"X-Api-Key": "sk_live_YOUR_KEY"},
)
r.raise_for_status()
print(r.json()["data"])
const res = await fetch("https://api.synergicapis.com/oil-imports/latest", { headers: { "X-Api-Key": "sk_live_YOUR_KEY" }, }); const { data } = await res.json(); console.log(data);
Live demo
Real request against the production API — no key needed here (demo endpoint, 5 requests/minute).
Press the button to fetch the latest official figures.