Resolution

One series, every dimension named by the caller

Structured query: the caller names the dataset, ISO3 countries, an ISO period range and a member code for every dimension (see /v1/datasets/{id}/structure and /v1/schema/series.json). Nothing is guessed or relaxed. Status is ok, empty (with a reason) or refused (licence_unverified, no_data_path, not_in_serve_set, reader_refused, ambiguous_selection). Metered like /v1/data: only an uncached upstream fetch is charged; refusals, empties and 4xx/5xx are free. A body that is not JSON is 400 bad_json.

post/v1/series

Request

  • Base URL: https://api.stackdata.io
  • URL: https://api.stackdata.io/v1/series
  • Auth: one of:
    • none
    • API key in header X-API-Key

Request body

datasetstring required

A dataset id from the catalog, as returned by search (/v1/search, or the search_datasets MCP tool), e.g. "ilo-sdmx:DF_X".

countriesstring[] required

ISO 3166-1 alpha-3 codes (e.g. "JPN") or an aggregate code listed in the dataset's /structure. 1 to 25 entries.

selectobject required

A member code for every dimension of the dataset (other than geography and time) as listed in /structure, including frequency. Every dimension must be named; a missing or unknown dimension or code is a 400, never defaulted.

Response

An ok, empty or refused answer. ok carries observations (each with its own provenance, including the raw period string); empty carries a reason; refused carries a reason and, for reader_refused and ambiguous_selection, a detail. An empty observations array is never a bare success: it is empty or refused.

status'ok' | 'empty' | 'refused' required
requestobject required

The request as received.

reasonstring

On empty, why there is nothing. On refused, one of licence_unverified, no_data_path, not_in_serve_set, reader_refused, ambiguous_selection.

detailstring

With reader_refused and ambiguous_selection; also an empty caused by a reader's own message.

datasetstring

Present on refusals.

unparsed_periodsstring[]

Present only when the source returned period strings that could not be normalised; those points are not in observations.

Changes

No recorded changes to this operation across all 1 revision of this API.