pxwebapi-v2 - SKILL.md Agent Skill

name: pxwebapi-v2 description: > Access official statistics from any PxWebApi v2 installation. Use when querying statistical databases from agencies like Statistics Sweden (SCB), Statistics Norway (SSB), Statistics Finland, Statistics Iceland, or any other institution running PxWebApi v2. Trigger on "Swedish statistics", "SCB data", "Nordic statistics", "PxWeb", "PxWebApi", "statistical database", "Statistikdatabasen", or similar. Covers table search, metadata, data queries, codelists, and saved queries.

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 multiple national statistical institutes.

Known PxWebApi v2 installations

Agency	Country	Base URL	Languages
Statistics Norway (SSB)	Norway	`https://data.ssb.no/api/pxwebapi/v2`	no, en
Statistics Sweden (SCB)	Sweden	`https://statistikdatabasen.scb.se/api/v2`	sv, en

More agencies are expected to migrate to v2. Check /config at the base URL to verify a v2 installation.

Important: Each installation has its own limits (cell count, rate limiting), table IDs, variable codes, and codelists. Always check /config and metadata for the specific installation you are querying.

API endpoints

Endpoint	Method	Purpose
`/tables`	GET	Search and list tables
`/tables/{id}`	GET	Get info about a single table
`/tables/{id}/metadata`	GET	Get metadata (variables, codes, codelists)
`/tables/{id}/defaultselection`	GET	Get the table's default selection
`/tables/{id}/data`	GET / POST	Get data with filters
`/codelists/{id}`	GET	Look up a codelist
`/savedqueries`	POST	Create a saved query
`/savedqueries/{id}`	GET	Get a saved query
`/savedqueries/{id}/data`	GET	Run a saved query and get data
`/savedqueries/{id}/selection`	GET	Get the selection of a saved query
`/config`	GET	API configuration (limits, formats, languages)

All endpoints accept the lang parameter. Supported languages depend on the installation.

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. Then set the base URL accordingly.

Always start by checking the configuration:

GET {base_url}/config

This returns maxDataCells, maxCallsPerTimeWindow, timeWindow, supported languages, and available output formats.

Step 2: Search for tables

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

Search parameters:

Parameter	Type	Description
`query`	string	Free-text search keywords
`pastDays`	int	Limit to tables updated in the last N days
`includeDiscontinued`	bool	Include discontinued series (default: false)
`pageNumber`	int	Page number for pagination
`pageSize`	int	Number of results per page

Search tips:

Use the local language terms of the agency for best results
title: prefix restricts search to the title field
Truncation: population* matches anything starting with "population"
Boolean operators: trade AND fish*
Check lastPeriod and timeUnit in results

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 array — Number of values per variable
dimension object — Detailed info per variable: codes (category.index), labels (category.label), units (category.unit), elimination flag (extension.elimination), and available codelists (extension.codelists)
role object — Which variables have role as time, geo, or metric

Key rules:

Variables with elimination: true can be omitted — they are summed automatically
Variables with elimination: false MUST be included in the query. Tid (time) and ContentsCode are never eliminable.
ContentsCode tells you what is measured — check category.unit for unit and decimals

Codelists: Group values into higher aggregation levels. Two types: Aggregation (agg_ prefix) maps many-to-one; Valueset (vs_ prefix) shows an alternative set of values. See references/codelists-and-filters.md for details.

Default selection: Use GET {base_url}/tables/{id}/defaultselection as a starting point for large tables.

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.

POST (recommended for complex queries)

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

Key patterns: top(N) = last N values, from(value) = from and including, range(from,to) = interval, * = all values. Wildcards * and ? can be used for pattern matching. See references/codelists-and-filters.md for complete syntax.

Output formats

Format	Value	Use
json-stat2	`json-stat2`	Default, machine-readable, rich metadata
CSV	`csv`	Simple tabular format
Excel	`xlsx`	For end users
HTML	`html`	Table for display
PX	`px`	Traditional PX format
JSON-PX	`json-px`	JSON variant of PX

Note: Not all formats may be available at every installation. Check /config for dataFormats.

OutputFormatParams (can be combined): UseCodes, UseTexts, UseCodesAndTexts, IncludeTitle, SeparatorTab / SeparatorSpace / SeparatorSemicolon.

Important limits:

Check /config for maxDataCells — this varies between installations (e.g. SSB: 800,000, SCB: 150,000)
Rate limiting: /config shows maxCallsPerTimeWindow and timeWindow
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
Always include source attribution listing every table ID used — if multiple tables were combined, list all of them (e.g. "Source: {Agency}, tables {id1}, {id2}, …"); never omit a source table
Explain what the numbers mean in context — in the user's language
Present units clearly (count, percent, index, currency)
Offer to visualize the data or download in another format

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": "Tid", "valueCodes": ["top(5)"] }
    ]
  },
  "outputFormat": "json-stat2"
}

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

Response format

Both metadata and data are returned as json-stat2 by default. See references/json-stat2.md for the Dataset structure, row-major indexing and status codes (format spec — also applies to non-PxWeb providers like Eurostat). See references/api-details.md for PxWebApi-specific configuration.

Rules

Always:

Search first — never guess table IDs
Check metadata before building a query
Check /config for the specific installation's limits
Filter on time to keep datasets manageable
Show source with agency name and table ID
Present units clearly
Check the elimination flag — only omit variables that allow it

Never:

Fetch data without filters from large tables
Assume table IDs, variable codes, or codelists are the same across installations
Mix codes from different codelists
Present data without units
Ignore the status field — it may indicate missing or confidential values

Troubleshooting

See references/troubleshooting.md for common errors and solutions.

Fallback

If the API is not available, refer the user to the agency's web-based statistical database.