---
title: "Published structure of one dataset (free, unmetered)"
method: GET
path: "/v1/datasets/{dataset_id}/structure"
tags: ["Discovery"]
---

# Published structure of one dataset (free, unmetered)

`GET /v1/datasets/{dataset_id}/structure`

## Request

- Base URL: `https://api.stackdata.io`
- URL: `https://api.stackdata.io/v1/datasets/{dataset_id}/structure`
- Auth: one of:
  - none
  - API key in header `X-API-Key`

Dimensions, member codes and labels, totals, frequencies, periods, the ISO3 countries
the dataset can serve, and whether it is servable. Use it to build a `POST /v1/series`
request. Never metered.

`countries` lists an ISO3 code only when our country table holds it AND the
publisher's own label for the source code names that country: a code's shape is
never enough (Eurostat's `FRA` is its overseas-departments region and `POL`
Polynesia; France is `FR`). Every other geography code is listed under
`aggregates`, by its native code. Labels carry the dataset's language as `lang`
(`und` when the catalog does not record it). On the frequency dimension each
member states the ISO period frequency it serves (`period_frequency`: `A`, `Q`, `M`,
or null when the structured path does not serve it). `max_countries` is how many
geographies one request may name: 1 on readers that serve one geography per
request (PxStat, PxWeb, StatBank, OData, DataStat, e-Stat, BDL, pindica).

On national PxWeb and PxStat tables a region axis can appear as an ordinary
dimension: selecting a region member there returns that region's values,
attributed to the national ISO3 the request named (the echo in `resolved.select`
shows the region chosen).
Unservable datasets (`licence_unverified`, `no_data_path`) answer from the catalog
alone: no structure is fetched from the publisher, so `dimensions` is empty.

## Path parameters

- `dataset_id` string, required

## Response `200`

The structure view. A dataset that cannot be served says so here
(`servable: false` with `not_servable_reason`) rather than being hidden.

- Structure: What a `POST /v1/series` request can name for one dataset. Geography and time are not dimensions here: geography is `countries` (ISO3, plus `aggregates`), time is `period`.
  - `dataset` string, required
  - `title` string, nullable
  - `publisher` string
  - `unit` string, nullable
  - `licence` object
  - `servable` boolean, required
  - `not_servable_reason` string, nullable: Set when `servable` is false (e.g. `licence_unverified`, `no_data_path`, `not_in_serve_set`).
  - `frequencies` string[], required: Frequency codes served. An empty list means undeclared (the period's frequency is accepted and filtered after the fetch).
  - `periods` object, nullable, required: Declared coverage per frequency, `{first, last}` in ISO form. Null means undeclared.
  - `countries` string[], required: ISO 3166-1 alpha-3 codes this dataset can serve. Listed only when our country table holds the code and the publisher's label for its source code names that country.
  - `aggregates` object[], required: Native region/aggregate codes usable in `countries` as given — every geography code the publisher lists that is not bound to a listed country (a code spelled like a listed country's ISO3 is left out, because a request naming it means the country).
    - `code` string
    - `label` string
    - `lang` string
  - `max_countries` integer, required: How many distinct geographies one request may name. 25, or 1 on readers that serve one geography per request.
  - `dimensions` StructureDimension[], required
    - `id` string, required
    - `role` 'frequency': Present on the frequency dimension.
    - `members` StructureMember[], required
      - `code` string, required
      - `label` string, required: The publisher's label
      - `lang` string, required: Language of `label`: the dataset's recorded title language, `und` when the catalog does not record one.
      - `period_frequency` 'A' | 'Q' | 'M' | 'null', nullable: On the frequency dimension only. The ISO period frequency this member serves (by the publisher's label, else its code); null when the structured path does not serve it — selecting it is `400 period_frequency_mismatch`.
      - `total` boolean: True on the member the reader would use as the aggregate (total) default.
      - `default_reason` string, nullable: Why this member is the default; present with `total`.

## Other responses

- `404`: Unknown dataset (`unknown_dataset`).
- `502`: The source could not deliver the structure (`upstream_failed`).

---

[API](https://skmtc.dev/stackdata/apis/stackdata-api.md) · [All operations](https://skmtc.dev/stackdata/apis/stackdata-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stackdata/apis/stackdata-api/revisions/91358ae3f6e8?raw)