Tutorial: SSB (Statistics Norway)

Economics

Data source: Statistics Norway (SSB)

Overview

SSB (Statistics Norway) wraps Statistics Norway (SSB), handling authentication, pagination, and rate limits for you. This tutorial covers all 6 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-ssb": {
      "url": "https://context.gnist.ai/mcp/ssb/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_tables`

Search SSB's statistical table catalog by keyword. SSB (Statistics Norway) publishes thousands of tables covering population, employment, income, housing, trade, prices, health, education, and more. This tool searches the full catalog. Common queries: 'population', 'GDP', 'consumer price index', 'unemployment', 'housing prices', 'immigration', 'wages', 'births', 'exports'. Args: query: Search keywords (e.g. 'population by municipality'). lang: Language — 'en' for English, 'no' for Norwegian (default 'en'). Returns: List of matching tables with table_id, title, path, and relevance score. Use the table_id with get_table_metadata or get_data to explore further.

Parameter	Type	Required	Description
`query`	string	required	Search keywords (e.g. 'population by municipality').
`lang`	string	optional	Language — 'en' for English, 'no' for Norwegian (default 'en'). (default: `en`)

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

import httpx

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

`get_table_metadata`

Get the structure of an SSB 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_id: SSB table ID (e.g. '07459' for population, '03013' for CPI). lang: Language — 'en' or 'no'. Returns: Table title and list of variables with codes, labels, and valid values.

Parameter	Type	Required	Description
`table_id`	string	required	SSB table ID (e.g. '07459' for population, '03013' for CPI).
`lang`	string	optional	Language — 'en' or 'no'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/ssb/" \
  -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_id": "'07459'"}}}'

import httpx

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

`get_data`

Query data from an SSB 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": ["0"]} - 'top': last N periods, e.g. {"code": "Tid", "filter": "top", "values": ["5"]} - 'all': all values, e.g. {"code": "Boligtype", "filter": "all", "values": ["*"]} Example — Norway total population, last 5 years (table 07459): filters=[ {"code": "Region", "filter": "item", "values": ["0"]}, {"code": "ContentsCode", "filter": "item", "values": ["Personer1"]}, {"code": "Tid", "filter": "top", "values": ["5"]} ] Args: table_id: SSB table ID. 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 'no'. 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_id`	string	required	SSB table ID.
`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 'no'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/ssb/" \
  -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_id": "12345"}}}'

import httpx

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

`list_subjects`

List SSB's top-level subject categories. Returns the 23 main statistical subject areas (e.g. Population, Labour market, National accounts, Health, Education). Use the returned IDs with browse_subject to navigate deeper into the hierarchy. Args: lang: Language — 'en' or 'no'. Returns: List of subject categories with id, text, and type (folder or table).

Parameter	Type	Required	Description
`lang`	string	optional	Language — 'en' or 'no'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/ssb/" \
  -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/ssb/",
    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 SSB table hierarchy by providing a path from list_subjects or a previous browse_subject call. Returns child folders and tables. Example paths: 'bb' (Construction/housing), 'bb/bb01' (Building activity), 'al' (National accounts/public finances). Args: path: Subject path (e.g. 'bb', 'bb/bb01'). lang: Language — 'en' or 'no'. 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. 'bb', 'bb/bb01').
`lang`	string	optional	Language — 'en' or 'no'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/ssb/" \
  -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": "'bb'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ssb/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'path': "'bb'"}, 'name': 'browse_subject'}},
)
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/ssb/" \
  -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/ssb/",
    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 search_tables 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 SSB (Statistics Norway) provide?

Norwegian official statistics — population, employment, income, housing, trade, and economic data. It exposes 6 tools: search_tables, get_table_metadata, get_data, list_subjects, browse_subject, 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 SSB (Statistics Norway) API return?

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