Economics

Data source: Statistics Finland (Tilastokeskus)

REST Bridge Endpoint https://context.gnist.ai/rest/statfin/

Authentication

All requests require a Gnist-API-Key header (or api_key query parameter).

Free tier: 100 calls/day. Get your API key.

Tools (6)

search_tables
get_table_metadata
get_data
list_subjects
browse_subject
report_feedback

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")

Request Body

{
  "query": "example"
}

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")

Request Body

{
  "table_path": "example"
}

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")

Request Body

{
  "table_path": "example"
}

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")

Request Body

{
  "query": "example"
}

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")

Request Body

{
  "path": "example"
}

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")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/statfin/search_tables" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"query": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/statfin/search_tables",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "query": "example"
},
)
print(resp.json())