Generic Pxweb V2 Skill

PxWebApi v2 — Generic Skill

This skill guides you through using PxWebApi v2 to search, explore, and retrieve official statistics. PxWebApi v2 is developed by Statistics Sweden (SCB) and used by several national statistical institutes. Everything below that says varies by installation has been verified to vary on the three installations listed under "Known installations".

Data integrity — the base rule

Official statistics carry an agency's name. A wrong number under that citation damages trust in the agency, not just in the answer. This rule outranks everything else in this skill:

Never state a number you have not fetched from the API in this conversation.

• No numbers from memory. If you did not run the query, you do not have the number — including numbers you are confident about. Populations, price indices and unemployment rates all move, and training data has a cutoff.
• No numbers from other sources in the same answer. Point the user elsewhere rather than blending.
• If the API fails, say so. No estimates, no "roughly". See Fallback.
• No interpolation or projection. A period missing from the extract is missing from the answer.
• Mark your own calculations. Growth rates, shares and sums are yours, not the agency's — show which fetched numbers they rest on, and keep the API's decimals (category.unit.decimals).
• Show status values as they are. Missing, provisional and confidential values belong in the table, not hidden or replaced by zero.
• Show mandatory notes. When extension.noteMandatory is set, the agency has decided the note travels with the figure. Omitting it presents the number without the caveat the agency attached. See Step 5.
• Check discontinued and lastPeriod. Tables are closed and the series often continues in a new one. If you use a discontinued table, say so and give the last period.

Not finding the number is a valid answer. An honest "not found", with suggested search terms, beats a plausible number that is wrong.

Known PxWebApi v2 installations

All three verified live 2026-09-08. They differ more than the shared API shape suggests — the full comparison is in references/api-details.md; the four differences that change how you query:

• Default data format. SSB and SCB return json-stat2 when outputFormat is omitted; Latvia returns PX (application/octet-stream). Always set outputFormat=json-stat2 explicitly.
• Cell limit. maxDataCells is 800 000 at SSB, 150 000 at SCB and 10 000 at Latvia — an 80× spread. Read it from /config every time.
• Variable names. The metric is ContentsCode on all three, but time is Tid (SSB, SCB) or TIME (Latvia) and geography is Region or AREA. Read names from role and id, never assume.
• Period codes. Quarters are 2024K2 at SSB/SCB and 2026Q2 at Latvia; weeks are 2026U35 (SSB), 2026V30 (SCB), 2026W13 (Latvia). Read the codes from metadata before writing a time filter.

These agencies were checked on 2026-08-30 and are still v1-only — no v2 endpoint responds at any of the usual URL patterns. Use generic-pxweb-v1-skill for them:

SSB and SCB each still run their v1 API alongside v2 (data.ssb.no/api/v0/, api.scb.se/OV0104/v1/doris/), so a v1 URL from a user's old script is not evidence that the agency lacks v2.

Which version is this installation?

1. GET {base}/config — a v2 installation returns a JSON object with apiVersion, maxDataCells, dataFormats.
2. If that fails, try v1's config, which is a query parameter, not a path: GET {v1_base}?config. The v1 path form /config returns 400.

Check that the body parses as JSON — do not trust the status code. Statistics Greenland answers GET /api/v2/config with HTTP 200, Content-Type: text/html, and the body CONFIG404;…<br>Filen findes ikke - File not found (re-verified 2026-09-08). A version check that only looks at the status code concludes "v2 exists" and every subsequent call fails confusingly.

For SSB or SCB queries, prefer the dedicated sibling skills (ssb-pxwebapi-v2, scb-pxwebapi-v2) — they have agency-specific examples, curated table catalogs, and operational details that this generic skill does not cover.

API endpoints

All endpoints accept the lang parameter; supported languages depend on the installation. Installation-specific configuration, the rate-limit table and output formats: references/api-details.md. The json-stat2 document itself (structure, indexing, extension, status codes): references/json-stat2.md — the format is shared with Eurostat and other non-PxWeb providers.

Workflow

Follow these steps in order. Never skip the metadata step.

Step 1: Identify the installation

Determine which PxWebApi v2 installation the user needs. If unclear, ask. Set the base URL, then GET {base_url}/config first — the version check above tells you how to read it, and the fields are in references/api-details.md.

Step 2: Search for tables

Use GET {base_url}/tables with the query parameter.

Search parameters:

Search tips:

• Use the agency's local-language terms; add a word from the expected title when the hit list is long
• title: restricts to the title field; AND, OR and "phrase"~N work (the engine is Lucene). The default operator between words differs: AND at SSB and SCB (population region = population AND region), OR at Latvia (population region = population OR region, 494 hits against 125). Write the operator out in any query you intend to share
• Truncation matches the stemmed index term, so truncate short. population* returns 0 hits at Latvia and at SSB's English index; popul* returns 203 and 403. Swedish folkmängd* returns 0 at SCB, folkmäng* returns 117. Cut the word before its ending, and check page.totalElements before concluding a table does not exist. A leading wildcard (*ulation) returns HTTP 500 at Latvia
• Default pageSize is 20. A table in position 47 is never on page 1 — raise pageSize or page through

Screen candidates from the search hit, before spending a metadata call each. A /tables hit carries more than the title:

discontinued is not an aliveness test — compare lastPeriod with today. Agencies freeze a table and continue the series in a new one without setting the flag: SCB's TAB638 stops at 2024 with discontinued: null while TAB6471 carries 2025 onwards. At Latvia the key is absent from the /tables hit altogether. If lastPeriod is further back than the table's frequency should allow, find the successor before answering. The catalogue can also lag the other way: Latvia's /tables/IRS010m says lastPeriod: 2026M04 while the data run to 2026M07 — take "latest" from a top(1) on the data, not from the hit.

Present the 3–5 most relevant hits with table ID, title, last period, time frequency, and discontinued status.

Step 3: Explore metadata

Use GET {base_url}/tables/{id}/metadata to understand the table structure.

Metadata is returned in json-stat2 format. Focus on:

• id array — variable names; size gives the number of values per variable
• dimension object — per variable: codes (category.index), labels (category.label), units (category.unit), and extension with elimination and the available codelists
• role object — start the analysis here. role.metric is what is measured (ContentsCode on all three known installations; read category.unit for unit and decimals). role.time is the time dimension (Tid or TIME). role.geo is optional and installation-dependent — SSB and Latvia set it (Region, AREA), SCB does not, even on tables with 290 municipalities. Look for a geographic variable in id first; only when none exists does the data cover the whole area. Do not ask the user. Remaining variables in id are breakdown dimensions
• note array + extension.noteMandatory — table notes, and which of them must be shown, keyed by index into note. See Step 5
• extension (root) — noteMandatory, contact, PX metadata under extension.px, and discontinued when set. firstPeriod/lastPeriod/timeUnit are not here — they are on the /tables hit and GET /tables/{id}

Key rules:

• Read elimination from the metadata response only — in a data response the field describes the extract you received, not the table's contract. Omitting an eliminable variable removes it from the response entirely (from id and dimension, not as a total row); note it yourself. Metadata does not distinguish a dimension with a predefined total code from one summed on the fly — scan category.label for a total, or probe; eliminationValueCode appears only in data responses that include the total (verified on SSB, SCB and Latvia). Which variables are eliminable is a property of the table, not of the variable name: Alder is optional in SCB's TAB638 and mandatory in TAB6471. Details: references/json-stat2.md
• Omitting a variable with elimination: false fails with 400 — "Missing selection for mandantory variable" (the API's own spelling, identical on all three installations; quote it as-is). This is the sharpest v1/v2 difference: v1 returns all the variable's values instead of failing.

Codelists: group values into higher aggregation levels — agg_ maps many-to-one, vs_ is an alternative value set. The codelist's own codes are what go in valueCodes (read them from GET /codelists/{id}), and the response does not record which codelist produced a figure. See references/codelists-and-filters.md.

Default selection: GET {base_url}/tables/{id}/defaultselection is a starting point for large tables. A GET /data with no selection is not an error and does not return the whole table — it silently returns the default selection, HTTP 200, with eliminable dimensions outside it summed away unannounced. SCB's TAB6471 returns three cells with Region absent from the response entirely; Latvia's default response also orders id differently from the metadata. Always build the selection yourself — figures and verification in references/troubleshooting.md.

Step 4: Build and run query

PxWebApi v2 supports both GET and POST for data retrieval. You can also use the agency's web interface to build queries graphically — look for a "Save" or "API query" option to get ready-made GET URLs and POST bodies.

Always pass outputFormat=json-stat2 explicitly. The default is per installation: json-stat2 at SSB and SCB, PX at Latvia — a body starting CHARSET="ANSI"; is what you get when you forget.

POST (recommended for complex queries)

The example uses Region, ContentsCode and Tid — Nordic names. At Latvia the same query reads AREA, ContentsCode and TIME. Substitute the actual names from role.geo, role.metric and role.time.

POST {base_url}/tables/{id}/data?outputFormat=json-stat2
Content-Type: application/json

{
  "selection": [
    { "variableCode": "Region", "valueCodes": ["01"] },
    { "variableCode": "ContentsCode", "valueCodes": ["Population"] },
    { "variableCode": "Tid", "valueCodes": ["top(5)"] }
  ]
}

GET (simpler queries, shareable URLs)

GET {base_url}/tables/{id}/data?valueCodes[Region]=01&valueCodes[ContentsCode]=Population&valueCodes[Tid]=top(5)&outputFormat=json-stat2

Filter expressions in valueCodes

All of these work, verified on all three installations: top(N) = last N values, bottom(N) = first N, from(code) = from and including, to(code) = up to and including, range(from,to) = closed interval, top(N,offset) / bottom(N,offset) = N values starting offset from the end / start, * and ? wildcards (2025M* = one year of months), and explicit lists.

In a GET URL, any expression that contains a comma must be wrapped in square brackets — valueCodes[Tid]=[range(2024M01,2024M03)], [top(3,2)] — because a bare comma is the list separator (valueCodes[Tid]=2024M01,2024M02). Unwrapped, range(...) returns 400 — "Illegal selection expression" on every installation, which is easy to misread as the function not existing. Single-argument forms (top(3), from(2024M01)) work with or without brackets. In a POST body it is the other way round: write the bare string ("valueCodes": ["range(2024M01,2024M03)"]); a bracketed string is looked up as a code and fails with Non-existent value. Expressions can be mixed with explicit codes (["2015", "top(2)"]), but two function expressions in one array give the union — ["from(2024M01)", "to(2024M03)"] is 319 periods, not the interval. With curl, pass -g: the brackets in valueCodes[Var] are otherwise parsed by curl itself (bad range in URL) — see references/troubleshooting.md.

For the time dimension, prefer top(N) or from(code) over range() and explicit periods — relative filters capture new periods automatically, so shareable URLs and saved queries stay current instead of freezing on whatever was latest when they were written. Use range() when the closed interval is the point. Full syntax: references/codelists-and-filters.md.

Output formats

Default json-stat2; also csv, xlsx, html, px, json-px, and at some installations parquet — dataFormats in /config is authoritative, and its spelling matters (Latvia lists json_stat2 too, which returns 400). Parameters (UseCodesAndTexts, IncludeTitle, separators, heading/stub): references/api-details.md.

Important limits:

• maxDataCells from /config — 10 000 to 800 000 across the known installations; exceeding it is 400 — "Too many cells selected"
• Rate limiting: check both /config and the response headers — SSB announces only in x-ratelimit-* headers, SCB and Latvia in /config and X-Rate-Limit-* headers (a different spelling; match both). See references/api-details.md
• GET URLs cannot exceed ~2,100 characters — use POST for complex queries
• Start narrow — it's easier to expand than to handle too much data

Step 5: Present results

• Display data in a clean markdown table
• Say which dimensions you collapsed and which codelist you used — the response records neither. If the reader cannot reconstruct your query from your answer, the extract is not reproducible. See "What json-stat2 cannot express" in references/json-stat2.md
• Show mandatory notes. extension.noteMandatory is keyed by index into the root note array and travels with the data response, so it costs no extra call. A mandatory note may constrain your own arithmetic — SCB's population tables from 2025 carry disclosure-control noise, so published totals are not the sum of their parts; say so when you sum
• Always include source attribution listing every table ID used — if multiple tables were combined, list all of them; never omit a source table. /config sourceReferences gives the agency's own citation string per language
• Explain what the numbers mean in context — in the user's language
• Present units clearly (count, percent, index, currency); for an index, give the base period
• Offer to visualize the data or download in another format. If the data came from SSB and the ssb-chart-skill skill is available in the environment, use it for the visualization

Step 6: Saved queries (optional)

To create a shareable, reusable query:

POST {base_url}/savedqueries
Content-Type: application/json

{
  "tableId": "{id}",
  "language": "en",
  "selection": {
    "selection": [
      { "variableCode": "Region", "valueCodes": ["01"] },
      { "variableCode": "ContentsCode", "valueCodes": ["Population"] },
      { "variableCode": "Tid", "valueCodes": ["top(5)"] }
    ]
  },
  "outputFormat": "json-stat2",
  "outputFormatParams": []
}

Both outputFormat and outputFormatParams are required in the savedqueries body — pass outputFormatParams: [] if you don't need any. Include all non-eliminable variables in the selection, otherwise the API returns HTTP 400. The endpoint exists on all three installations.

Useful for reports that are updated regularly — top(N) always returns the latest periods.

Pitfalls — never

The integrity rules at the top always apply — in addition:

• Fetch data without filters and assume you got the table — you get the default selection, HTTP 200, with eliminable dimensions summed away unannounced (see Step 3)
• Assume table IDs, variable codes, codelists, limits, default format or period-code letters are the same across installations — re-check /config and metadata when switching installation
• Mix codes from different codelists
• Present data without units

Fallback

Common errors and their causes (400 titles, 403, 404, 429, PX instead of JSON, empty search results): references/troubleshooting.md.

If the API is not available:

1. Say plainly that the data could not be fetched. Never fill the gap with numbers from memory — without API access you deliver guidance, not statistics
2. Refer the user to the agency's web-based statistical database
3. Suggest search terms based on the question