{"openapi":"3.0.3","info":{"title":"Gnist Context — Statistics Finland (Tilastokeskus)","description":"Finnish official statistics — population, employment, income, housing, trade, and economic data.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/statfin/`\n- **Toolkit page:** `/toolkits/statfin`\n- **Full API spec:** `/api/openapi.json`\n- **Get an API key:** `/signup`","version":"1.0.0","contact":{"name":"GnistAI","url":"https://gnist.ai"}},"servers":[{"url":"https://context.gnist.ai","description":"Production"}],"paths":{"/rest/statfin/search_tables":{"post":{"tags":["Economics"],"summary":"search_tables","description":"Search Statistics Finland's statistical table catalog by keyword.\n\nStatistics Finland (Tilastokeskus) publishes thousands of tables covering\npopulation, employment, income, housing, trade, prices, health, education,\nand more. This tool searches the full StatFin catalog.\n\nCommon queries: 'population', 'GDP', 'consumer price index', 'unemployment',\n'housing prices', 'immigration', 'wages', 'births', 'exports'.\n\nArgs:\n    query: Search keywords (e.g. 'population by municipality').\n    lang: Language — 'en' for English, 'fi' for Finnish (default 'en').\n\nReturns:\n    List of matching tables with table_path, title, and relevance score.\n    Use the table_path with get_table_metadata or get_data to explore further.","operationId":"statfin_search_tables","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Search keywords (e.g. 'population by municipality').","type":"string"},"lang":{"default":"en","description":"Language — 'en' for English, 'fi' for Finnish (default 'en').","type":"string"}},"required":["query"],"type":"object"}}}}}},"/rest/statfin/get_table_metadata":{"post":{"tags":["Economics"],"summary":"get_table_metadata","description":"Get the structure of a Statistics Finland table — its dimensions, variables, and valid values.\n\nUse this before querying data to understand what filters are available.\nEach variable lists its valid codes and labels. Variables marked 'elimination: true'\ncan be omitted from queries to get aggregated totals.\n\nTime variables are flagged with 'time: true'. Time codes follow patterns:\n'2024' (annual), '2024Q3' (quarterly), '2024M06' (monthly).\n\nArgs:\n    table_path: Table path from search results, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'.\n    lang: Language — 'en' or 'fi'.\n\nReturns:\n    Table title and list of variables with codes, labels, and valid values.","operationId":"statfin_get_table_metadata","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"table_path":{"description":"Table path from search results, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'. Combine search result 'path' and 'table_id'.","type":"string"},"lang":{"default":"en","description":"Language — 'en' or 'fi'.","type":"string"}},"required":["table_path"],"type":"object"}}}}}},"/rest/statfin/get_data":{"post":{"tags":["Economics"],"summary":"get_data","description":"Query data from a Statistics Finland statistical table.\n\nWithout filters, returns the latest top_n time periods for all dimensions.\nWith filters, you can select specific dimension values.\n\nEach filter dict needs: 'code' (variable code from metadata), 'filter' type,\nand 'values' list. Filter types:\n- 'item': select specific codes, e.g. {\"code\": \"Vuosi\", \"filter\": \"item\", \"values\": [\"2024\"]}\n- 'top': last N periods, e.g. {\"code\": \"Vuosi\", \"filter\": \"top\", \"values\": [\"5\"]}\n- 'all': all values, e.g. {\"code\": \"Sukupuoli\", \"filter\": \"all\", \"values\": [\"*\"]}\n\nExample — Finland total population, last 3 years (table vaerak/statfin_vaerak_pxt_11rb.px):\nfilters=[\n    {\"code\": \"Sukupuoli\", \"filter\": \"item\", \"values\": [\"SSS\"]},\n    {\"code\": \"Tiedot\", \"filter\": \"item\", \"values\": [\"vaesto\"]},\n    {\"code\": \"Vuosi\", \"filter\": \"top\", \"values\": [\"3\"]}\n]\n\nArgs:\n    table_path: Table path, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'.\n    filters: List of dimension filters. See get_table_metadata for valid codes.\n    top_n: If no filters given, fetch this many latest time periods (default 5).\n    lang: Language — 'en' or 'fi'.\n\nReturns:\n    Parsed data with metadata (label, source, updated) and a list of records.\n    Each record has labeled dimension values and a 'value' field.","operationId":"statfin_get_data","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"table_path":{"description":"Table path, e.g. 'vaerak/statfin_vaerak_pxt_11rb.px'.","type":"string"},"filters":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"default":null,"description":"List of dimension filters. See get_table_metadata for valid codes."},"top_n":{"default":5,"description":"If no filters given, fetch this many latest time periods (default 5).","type":"integer"},"lang":{"default":"en","description":"Language — 'en' or 'fi'.","type":"string"}},"required":["table_path"],"type":"object"}}}}}},"/rest/statfin/list_subjects":{"post":{"tags":["Economics"],"summary":"list_subjects","description":"List Statistics Finland's top-level subject categories.\n\nReturns the main statistical subject areas (e.g. Population, Labour market,\nNational accounts, Health, Education). Use the returned IDs with browse_subject\nto navigate deeper into the hierarchy.\n\nArgs:\n    lang: Language — 'en' or 'fi'.\n\nReturns:\n    List of subject categories with id, text, and type (folder or table).","operationId":"statfin_list_subjects","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"lang":{"default":"en","description":"Language — 'en' or 'fi'.","type":"string"}},"type":"object"}}}}}},"/rest/statfin/browse_subject":{"post":{"tags":["Economics"],"summary":"browse_subject","description":"Browse a subject path to find sub-categories and tables.\n\nNavigate the Statistics Finland table hierarchy by providing a path from\nlist_subjects or a previous browse_subject call. Returns child folders and tables.\n\nExample paths: 'vaerak' (Population structure), 'tyti' (Labour force survey),\n'vtp' (Annual national accounts).\n\nArgs:\n    path: Subject path (e.g. 'vaerak', 'tyti').\n    lang: Language — 'en' or 'fi'.\n\nReturns:\n    List of items at this path — folders to navigate deeper, or tables to query.","operationId":"statfin_browse_subject","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"path":{"description":"Subject path (e.g. 'vaerak', 'tyti').","type":"string"},"lang":{"default":"en","description":"Language — 'en' or 'fi'.","type":"string"}},"required":["path"],"type":"object"}}}}}},"/rest/statfin/report_feedback":{"post":{"tags":["Economics"],"summary":"report_feedback","description":"Report a bug, feature request, or general feedback for this data source.\n\nUse this when something doesn't work as expected, when you'd like\na new feature, or when you have suggestions for improvement.\n\nArgs:\n    feedback: Describe the issue or suggestion.\n    feedback_type: One of 'bug', 'feature_request', or 'general'.","operationId":"statfin_report_feedback","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"feedback":{"type":"string"},"feedback_type":{"default":"general","type":"string"}},"required":["feedback"],"type":"object"}}}}}}},"tags":[{"name":"Economics","description":"Data sources: Economics"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"gnist-api-key","description":"API key passed via request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"gnist_api_key","description":"API key passed via query parameter."}}}}