---
title: "Variable dictionary and methodology notes"
method: GET
path: "/api/v1/research/pwt/definitions"
tags: ["Research"]
---

# Variable dictionary and methodology notes

`GET /api/v1/research/pwt/definitions`

Returns the variable dictionary shipped with the selected Penn World Table release - one entry per column with name, description (from the release Legend sheet), and type grouping. Includes a short methodology note summarising the expenditure- vs output-side real GDP distinction, the perpetual-inventory capital stock construction, TFP levels, and the human capital index. Use before querying other endpoints to confirm variable names and decode column meanings without reading the upstream user guide. Published under CC BY 4.0 with attribution to Penn World Table (Feenstra, Inklaar & Timmer, University of Groningen).

## Query parameters

- `version` string, nullable — Release selector. `pwt1100` (default) or `pwt1001` (legacy).

## Response `200`

Variable dictionary with grouped descriptions plus release methodology note.

- EnvelopePwtDefinitionsPayload
  - `data` PwtDefinitionsPayload, required — Variable dictionary + methodology note for one release.
    - `version` string, required — Release identifier.
    - `label` string, nullable — Release label (e.g. `PWT 11.0`).
    - `base_year` string, nullable — Real-GDP base year used by the release.
    - `doi` string, nullable — DataverseNL DOI of the release.
    - `release_time` string, nullable — DataverseNL publication timestamp of the release (ISO 8601 UTC).
    - `methodology_note` string, required — Short description of the Feenstra, Inklaar & Timmer methodology covering expenditure-side vs output-side real GDP, capital stock PIM, TFP levels, and the human capital index.
    - `user_guide_url` string, nullable — Link to the DataverseNL landing page for the release (user guide and what-is-new PDFs are linked from there).
    - `definitions_count` integer, required — Number of variable definitions returned.
    - `definitions` PwtVariableDefinition[], required — One entry per variable (including identifiers).
      - `name` string, required — Variable identifier as used in the Data sheet (e.g. `rgdpo`, `hc`, `ctfp`).
      - `description` string, nullable — Variable definition from the release Legend sheet. May include unit and base-year notes.
      - `type` string, nullable — Variable group. One of: identifier, real-gdp-ppp, current-price-ppp, national-accounts, exchange-rate-price-level, data-flag, expenditure-share, price-level-category, other.
    - `attribution` string, required — CC BY 4.0 attribution.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4c4530760ba1/schema)