---
title: "World aggregate time series (sum or mean across countries)"
method: GET
path: "/api/v1/research/pwt/world"
tags: ["Research"]
---

# World aggregate time series (sum or mean across countries)

`GET /api/v1/research/pwt/world`

Returns a Sugra-computed world aggregate across all Penn World Table countries for the requested variable subset. Pick `aggregation=sum` for level variables that add meaningfully across countries (rgdpo, rgdpe, pop, emp, cn, ccon), or `aggregation=mean` for unitless indices, shares, and price levels (hc, ctfp, cwtfp, labsh, pl_gdpo, csh_*). The Penn World Table upstream dataset does not ship a World row; this endpoint derives one at request time. Null values in the panel are skipped from the aggregate. Not every country contributes in every year, so the mix of contributing countries varies by year - keep this in mind for long-run world totals. Published under CC BY 4.0 with attribution to Penn World Table (Feenstra, Inklaar & Timmer, University of Groningen).

## Query parameters

- `variables` string, nullable — Comma-separated variable names to aggregate. Omit to receive every data variable (uses the requested aggregation method uniformly).
- `aggregation` string — Per-variable aggregation method. `sum` for level variables (rgdpo, pop). `mean` for indices and ratios (labsh, hc, pl_gdpo).
- `version` string, nullable — Release selector. `pwt1100` (default) or `pwt1001` (legacy).

## Response `200`

World-aggregate time series across the requested variable subset.

- EnvelopePwtWorldPayload
  - `data` PwtWorldPayload, required — World aggregate time series across the requested variable subset.
    - `version` string, required — Release identifier.
    - `aggregation` string, required — Per-variable aggregation method: `sum` (for level variables like rgdpo, pop) or `mean` (for indices and ratios like labsh, pl_gdpo, hc).
    - `variables` string[], required — Variable names included in the aggregate.
    - `observations` PwtObservation[], required — Year-indexed world-aggregate observations ordered ascending by year.
      - `year` integer, required — Observation year.
      - `countrycode` string, nullable — ISO 3166-1 alpha-3 country code.
      - `country` string, nullable — Country name as published.
      - `currency_unit` string, nullable — National currency unit.
    - `count` integer, required — Number of observation years returned.
    - `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.
- `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/4e2740743eb4/schema)