Tutorial: Statistics Finland (Tilastokeskus)

Economics

Data source: Statistics Finland (Tilastokeskus)

Overview

Statistics Finland (Tilastokeskus) wraps Statistics Finland (Tilastokeskus), 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-statfin": {
      "url": "https://context.gnist.ai/mcp/statfin/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_tables`

Search Statistics Finland's statistical table catalog by keyword. Statistics Finland (Tilastokeskus) publishes thousands of tables covering population, employment, income, housing, trade, prices, health, education, and more. This tool searches the full StatFin 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, 'fi' for Finnish (default 'en'). Returns: List of matching tables with table_path, title, and relevance score. Use the table_path 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, 'fi' for Finnish (default 'en'). (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/statfin/" \
  -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/statfin/",
    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 a Statistics Finland 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), '2024Q3' (quarterly), '2024M06' (monthly). Args: table_path: Table path from search results, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'. lang: Language — 'en' or 'fi'. Returns: Table title and list of variables with codes, labels, and valid values.

Parameter	Type	Required	Description
`table_path`	string	required	Table path from search results, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'. Combine search result 'path' and 'table_id'.
`lang`	string	optional	Language — 'en' or 'fi'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/statfin/" \
  -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": "'vaerak/statfin_vaerak_pxt_11rb.px'"}}}'

import httpx

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

`get_data`

Query data from a Statistics Finland 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": "Vuosi", "filter": "item", "values": ["2024"]} - 'top': last N periods, e.g. {"code": "Vuosi", "filter": "top", "values": ["5"]} - 'all': all values, e.g. {"code": "Sukupuoli", "filter": "all", "values": ["*"]} Example — Finland total population, last 3 years (table vaerak/statfin_vaerak_pxt_11rb.px): filters=[ {"code": "Sukupuoli", "filter": "item", "values": ["SSS"]}, {"code": "Tiedot", "filter": "item", "values": ["vaesto"]}, {"code": "Vuosi", "filter": "top", "values": ["3"]} ] Args: table_path: Table path, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'. 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 'fi'. 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	Table path, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'.
`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 'fi'. (default: `en`)

curl -X POST "https://context.gnist.ai/mcp/statfin/" \
  -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": "'vaerak/statfin_vaerak_pxt_11rb.px'"}}}'

import httpx

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

`list_subjects`

List Statistics Finland's top-level subject categories. Returns the 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 'fi'. Returns: List of subject categories with id, text, and type (folder or table).

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

curl -X POST "https://context.gnist.ai/mcp/statfin/" \
  -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/statfin/",
    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 Statistics Finland table hierarchy by providing a path from list_subjects or a previous browse_subject call. Returns child folders and tables. Example paths: 'vaerak' (Population structure), 'tyti' (Labour force survey), 'vtp' (Annual national accounts). Args: path: Subject path (e.g. 'vaerak', 'tyti'). lang: Language — 'en' or 'fi'. 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. 'vaerak', 'tyti').
`lang`	string	optional	Language — 'en' or 'fi'. (default: `en`)

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

import httpx

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

Finnish 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 Statistics Finland (Tilastokeskus) API return?

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