Data

indicator is the only required parameter. Everything else narrows the result, which is how you control both the row count and the cost.

format=csv streams rather than buffering, which usually matters more than the size of the response itself. The header row is fixed and the columns are in this order:

iso3,year,value,ci_lo,ci_hi
CHN,2000,3679.4,,
CHN,2001,4017.9,,
CHN,2002,4402.1,,
IND,2000,2358.7,,
IND,2001,2441.0,,
USA,2000,49951.3,,
USA,2001,50628.8,,

• Sent as text/csv with Content-Disposition: attachment; filename="<indicator>.csv", so a browser downloads it rather than rendering it.
• Nulls are empty fields, not the string NULL and not 0. Configure your reader accordingly — the trailing empty columns in the sample above are a series with no confidence interval.
• Identical cost, identical row cap, identical ordering.

cost = max(1, ceil(rows_returned / 100))

  40 rows   → max(1, ceil(0.4))  = 1
 125 rows   → max(1, ceil(1.25)) = 2
5325 rows   → max(1, ceil(53.25)) = 54

• Charged on rows returned, not rows requested. A generous query that happens to match little is cheap.
• Every error costs 0 — including too_many_rows, because the count runs before any data is read.
• Each request rounds up independently, so many small requests cost slightly more than one large one. Credits works this through.

A single request will not return more than 100,000 rows. Over that, the request is refused with the real count in the message, so you know exactly how far over you are.

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "too_many_rows",
    "message": "Query matches 412903 rows, over the 100000 limit. Narrow by countries or year range."
  }
}

There is no page 2. You narrow the query — fewer countries, or a shorter year range — and issue it again. Pagination has a complete chunking recipe that splits on countries first and years second, and halves adaptively if the estimate was wrong.

In practice the cap is generous: one indicator across every country and every year it holds is usually well under it. It bites on the deep-history series, some of which carry centuries.

• 400 bad_request — indicator missing. The details array names it.
• 400 bad_format — format was neither json nor csv. Case is normalised first, so CSV is accepted.
• 400 bad_range — from is greater than to. Only checked when you send both.
• 400 too_many_rows — over the cap. Costs nothing.
• 401 unauthorized — no key.
• 402 insufficient_credits — balance below the minimum. Nothing was served and nothing was charged.
• 403 display_only — the indicator’s licence permits display but not export. Permanent, and not fixable by topping up.
• 404 indicator_not_found — no such id, or a series we may not redistribute at all.

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "display_only",
    "message": "Indicator 'oecd.example_series' is display-only: viewable on the portal with attribution, but not available for CSV/JSON export."
  }
}

An unknown country code is not an error. Codes that match nothing simply contribute no rows, so countries=IND,XXX returns India’s rows with a 200. If a response is smaller than you expected, check your codes against /v1/countries. A year range outside the series behaves the same way: an empty array, a count of 0 — and, because there is a minimum, one credit.

• Ordering is stable. Always iso3 then year, ascending. There is no sort parameter, and none is needed — the result is deterministic.
• No pagination, on purpose. Offsets over an unbounded observation table are slow and fragile; a bounded query with a hard cap is neither. Chunk on the axes the data has.
• Only the open tier is exportable. Rankings and country detail will serve you a display-tier value; this endpoint will not. That is the difference between displaying and redistributing.
• Cache it yourself. Because this route needs a key, the response comes back private, no-store — it carries your balance, so no shared cache may hold it. Cache it inside your own application instead: the pipeline behind it runs daily at fastest, and a response you did not re-request costs no credit.
• Prefer latest_year to yr_max. A few series carry projection years. Bounding to with coverage.latest_year keeps forecasts out of a dataset that is meant to be observed.
• Reconcile from meta.count. It is exactly the number the charge was computed from, so a surprising bill is one division away from being explained.

• /v1/rankings — if what you want is every country for one year, this is a flat 1 credit and arrives already ordered.
• Pagination — the full-panel chunking recipe.
• Credits — the cost formula, worked through.
• Licensing — what you owe the provider.