Tutorial: SCB (Statistics Sweden)

Economics

Data source: Statistics Sweden (SCB)

Overview

SCB (Statistics Sweden) wraps Statistics Sweden (SCB), handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-scb": {
      "url": "https://context.gnist.ai/mcp/scb/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`list_subjects`

List SCB's top-level statistical subject categories. SCB (Statistics Sweden) publishes thousands of tables covering population, labour market, national accounts, trade, prices, environment, education, democracy, and more. This tool lists the main subject areas. Use the returned IDs with browse_subject to navigate deeper. Args: lang: Language — 'en' for English, 'sv' for Swedish (default 'en'). Returns: List of subject categories with id, text, and type (folder or table).

Parameter	Type	Required	Description
`lang`	string	optional	Language — 'en' for English, 'sv' for Swedish. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/scb/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_subjects", "arguments": {"lang": "en"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/scb/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lang': 'en'}, 'name': 'list_subjects'}},
)
print(resp.json())

`browse_subject`

Browse a subject path to find sub-categories and tables. Navigate the SCB table hierarchy by providing a path from list_subjects or a previous browse_subject call. Returns child folders and tables. Common top-level codes: AM (Labour market), BE (Population), BO (Housing), EN (Energy), FM (Financial markets), HA (Trade), HE (Household finances), HS (Health), JO (Agriculture), MI (Environment), NR (National accounts), NV (Business activities), PR (Prices), TK (Transport), UF (Education). When you reach a table (type='table'), use get_table_metadata with the full path to see its dimensions and variables. Args: path: Subject path (e.g. 'BE', 'BE/BE0101', 'AM/AM0401'). lang: Language — 'en' or 'sv'. Returns: List of items at this path — folders to navigate deeper, or tables to query.

Parameter	Type	Required	Description
`path`	string	required	Subject path (e.g. 'BE', 'BE/BE0101', 'AM/AM0401').
`lang`	string	optional	Language — 'en' or 'sv'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/scb/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "browse_subject", "arguments": {"path": "'BE'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/scb/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'path': "'BE'"}, 'name': 'browse_subject'}},
)
print(resp.json())

`get_table_metadata`

Get the structure of an SCB table — its dimensions, variables, and valid values. Use this before querying data to understand what filters are available. Each variable lists its valid codes and labels. Variables marked 'elimination: true' can be omitted from queries to get aggregated totals. Time variables are flagged with 'time: true'. Time codes follow patterns: '2024' (annual), '2024K3' (quarterly), '2024M06' (monthly). Args: table_path: Full path to the table (e.g. 'BE/BE0101/BE0101A/BefolkManadCKM'). lang: Language — 'en' or 'sv'. Returns: Table title and list of variables with codes, labels, and valid values.

Parameter	Type	Required	Description
`table_path`	string	required	Full path to the table (e.g. 'BE/BE0101/BE0101A/BefolkManadCKM').
`lang`	string	optional	Language — 'en' or 'sv'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/scb/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_table_metadata", "arguments": {"table_path": "'BE/BE0101/BE0101A/BefolkManadCKM'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/scb/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'table_path': "'BE/BE0101/BE0101A/BefolkManadCKM'"},
            'name': 'get_table_metadata'}},
)
print(resp.json())

`get_data`

Query data from an SCB statistical table. Without filters, returns the latest top_n time periods for all dimensions. With filters, you can select specific dimension values. Each filter dict needs: 'code' (variable code from metadata), 'filter' type, and 'values' list. Filter types: - 'item': select specific codes, e.g. {"code": "Region", "filter": "item", "values": ["00"]} - 'top': last N periods, e.g. {"code": "Tid", "filter": "top", "values": ["5"]} - 'all': all values, e.g. {"code": "Kon", "filter": "all", "values": ["*"]} Example — Sweden total population, last 5 months: table_path='BE/BE0101/BE0101A/BefolkManadCKM' filters=[ {"code": "Region", "filter": "item", "values": ["00"]}, {"code": "Alder", "filter": "item", "values": ["tot"]}, {"code": "Kon", "filter": "item", "values": ["1+2"]}, {"code": "ContentsCode", "filter": "item", "values": ["BE0101N1"]}, {"code": "Tid", "filter": "top", "values": ["5"]} ] Args: table_path: Full path to the SCB table. filters: List of dimension filters. See get_table_metadata for valid codes. top_n: If no filters given, fetch this many latest time periods (default 5). lang: Language — 'en' or 'sv'. Returns: Parsed data with metadata (label, source, updated) and a list of records. Each record has labeled dimension values and a 'value' field.

Parameter	Type	Required	Description
`table_path`	string	required	Full path to the SCB table.
`filters`	any	optional	List of dimension filters. See get_table_metadata for valid codes.
`top_n`	integer	optional	If no filters given, fetch this many latest time periods (default 5). (default: `5`)
`lang`	string	optional	Language — 'en' or 'sv'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/scb/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_data", "arguments": {"table_path": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/scb/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'table_path': 'example'}, 'name': 'get_data'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/scb/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/scb/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_subjects to find items, then get_table_metadata to get full details. This two-step pattern is common for exploring data before drilling down.

FAQ

What data does SCB (Statistics Sweden) provide?

Swedish official statistics — population, labour market, national accounts, trade, prices, environment, and economic data. It exposes 5 tools: list_subjects, browse_subject, get_table_metadata, get_data, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the SCB (Statistics Sweden) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.