workflow

Idescat data workflow

How to query the official statistics of Catalonia (Idescat) reliably. It applies both to the Idescat MCP server (https://api.idescat.cat/mcp) and to the Idescat Tables REST API (https://api.idescat.cat/taules/v2, OpenAPI description at https://www.idescat.cat/dev/api/taules/openapi.json). Responses follow the JSON-stat format (see the companion jsonstat skill for how to read them).

1. Choosing a statistic

Always start by listing the available statistics (MCP tool get_idescat_stats; API GET /taules/v2). For each statistic, check two key fields before choosing:

• datasets (boolean): if true the statistic is normalized and you can drill down to tables and data. If false, only the general information about the statistic is available.
• geo (array): available territorial breakdown levels (cat = Catalonia, prov = provinces, at = territorial plan areas, com = comarques and Aran, mun = municipalities, dis = districts, sec = census tracts). ALWAYS check geo before choosing a statistic for a territorial query: if comarca-level data is requested, pick a statistic whose geo includes com.

Population figures

When population data is requested there are several sources: the main and richest one is CENSPH (population and housing census, annual); for half-yearly estimates there is EP (population estimates, half-yearly); and there is also PMH (municipal population register, annual). By default use CENSPH (or EP for half-yearly data). NEVER use the PMH statistic for population data unless the user explicitly asks for it.

2. Data-retrieval flow

1. When specific data from a table is needed, fetch the table METADATA first (MCP get_table_metadata; API GET /taules/v2/{statistics}/{node}/{table}/{geo}). If the question is about a specific territory, pass the proper geo (e.g. com, mun, prov); if you don't know the territorial divisions available, list them first (MCP get_table_geo; API GET /taules/v2/{statistics}/{node}/{table}). Remember that without a territorial breakdown the response is the Catalonia total (cat), which does NOT include comarques, municipalities or provinces.
2. Check the metadata size field: multiply all its elements. If the product exceeds 20,000, do not fetch the whole table (the API rejects it with HTTP 416); filter first, or tell the user and offer the HTML link to the table.
3. Fetch the data (MCP get_table_data or render_table; API GET /taules/v2/{statistics}/{node}/{table}/{geo}/data) with optional filters:
   • For a SINGLE territory or a subset, filter on the territorial dimension (e.g. geo = com and filter COM=21), and/or limit the time periods with _LAST_ (e.g. _LAST_=2 for the last two periods).
   • Dimension filters are query parameters named after the dimension identifiers shown in the metadata, with comma-separated category codes as values (e.g. ?SEX=F&COM=01,TOTAL).
   • When you need the full dataset (≤ 20,000 cells), fetch it without filters.