Oil price API: get a country
Get a countryOne country in full: every series we hold for it and its stations.
PlansEvery plan
Cost1 call per request
ReturnsOne country in full
UpdatedHourly
What it is for
Everything we hold for one country: each series with its code, unit, currency, frequency and first and last dates, and how many stations we read there.
Take a series code from here to Series values, or a fuel code to Pump prices.
Good for
- Listing the fuels a country has
- Finding series codes for one country
- Checking how deep a country goes before a backfill
Parameters 1 in the path
| Name | Where and type | Required | What it does | Example |
|---|---|---|---|---|
country | path string | required | Goes in the address itself. | mx |
Try it runs against the live API with your key
No key yet? Get a free one; it is saved in this browser for every page.
The answer 200, application/json
| Field | Type | What it holds | Example |
|---|---|---|---|
country | string | Two letter country code | "MX" |
name | string | Our name for it | "Mexico" |
stations | integer | How many stations we read | 13858 |
series | array | Series code, or the series we hold | {"series":"coverage.mx.stations_daily... |
Example answer real, from what we hold now; long lists cut to three
GET /v1/countries/mx{ "data": { "country": "MX", "name": "Mexico", "stations": 13858, "series": [ { "series": "coverage.mx.stations_daily.diesel", "name": "Mexico diesel, stations in the daily average", "family": "coverage", "product": "diesel", "country": "MX", "region": null, "market": "stations_count", "unit": "stations", "currency": "", "interval": "day", "first_date": "2026-10-22", "last_date": "2026-10-29", "points": 8 }, { "series": "coverage.mx.stations_daily.gasoline_premium", "name": "Mexico gasoline premium, stations in the daily average", "family": "coverage", "product": "gasoline_premium", "country": "MX", "region": null, "market": "stations_count", "unit": "stations", "currency": "", "interval": "day", "first_date": "2026-10-22", "last_date": "2026-10-29", "points": 8 }, { "series": "coverage.mx.stations_daily.gasoline_regular", "name": "Mexico gasoline regular, stations in the daily average", "family": "coverage", "product": "gasoline_regular", "country": "MX", "region": null, "market": "stations_count", "unit": "stations", "currency": "", "interval": "day", "first_date": "2026-10-22", "last_date": "2026-10-29", "points": 8 } ] }, "meta": { "count": 72 } }
Errors every error has the same shape
| HTTP | Code | When | What to do |
|---|---|---|---|
| 401 | unauthorized | No key, or not a valid one | Send your key in the X-API-Key header; your account page shows it. |
| 400 | bad_request | A value is wrong or a required one is missing | The message names the parameter and the form it takes. |
| 422 | unknown_parameter | A parameter this endpoint does not take | Take it out; the parameters this endpoint takes are listed above. |
| 404 | not_found | No record by that country | Check the code; the list endpoint gives every one that exists. |
| 429 | rate_limited | Too many calls this minute | Wait the seconds in the Retry-After header, then call again. |
| 429 | quota_exceeded | Today's calls are used up | Wait for the day to reset at midnight UTC, or move to a larger plan. |
Dates and times are UTC. A point's date is the day its price took effect, or the first day of its week or month for weekly and monthly series. Conversions use each day's own rate, so a converted series moves with both the price and the exchange rate.