📊 INE - Estadísticas de España (INEbase)

Actor de Apify para consultar en lenguaje natural las estadísticas oficiales del INE (IPC, EPA, población, natalidad, migraciones, turismo, PIB, precios de vivienda...). Pensado para usarse desde un LLM vía el MCP de Apify: rellena el input JSON de una de las 7 acciones — nunca construyas tú mismo una URL de servicios.ine.es ni de www.ine.es, ni intentes hacer fetch directo al INE. Toda la interacción con el INE pasa por este actor.

🔑 Regla de oro: no inventes identificadores

tableId, seriesCode, operationCode y los ids dentro de filters ("variableId:valorId") son códigos opacos del INE que no siguen ningún patrón adivinable. Nunca los inventes. Si no los tienes:

1. No conoces la tabla/operación → action="search" con el tema, no la pregunta completa del usuario.
2. Necesitas filtrar por territorio, sexo, edad, sector... y no conoces el id → action="operation_variables".

Solo con esos ids en mano, pide los datos con table_data / series_data / operation_data.

🔀 Las 7 acciones (action)

action	Para qué	Campos relevantes
search	Primer paso casi siempre. Lenguaje natural → tablas candidatas (con tableId y la operación a la que pertenecen). No elige por ti: tú (el LLM) decides cuál usar después.	query, maxResults
table_data	Datos de una tabla concreta (todas sus series, o filtradas).	tableId, filters, nult/dateFrom/dateTo
series_data	Datos de una serie temporal concreta (cuando ya sabes el código exacto).	seriesCode, nult/dateFrom/dateTo
operation_variables	Lista las variables de una operación completa (sin variableId) o los valores posibles de una variable a nivel de TODA la operación (con variableId). ⚠️ Para variables con muchos valores (Municipios y similares) puede tardar 80-90 s: usa table_dimension_values si ya tienes una tabla concreta.	operationCode, variableId
table_dimension_values	Valores de una dimensión dentro de una tabla concreta (ej. los ~100 municipios de una tabla provincial, no los ~8.000 de toda España). Casi siempre preferible a operation_variables cuando ya tienes tableId.	tableId, dimension
operation_data	Datos filtrando por variable:valor sin conocer ninguna tabla.	operationCode, filters (obligatorio, con una variable por cada dimensión que clasifica la serie), periodicity (obligatoria)
refresh_catalog	Fuerza la reconstrucción del catálogo cacheado. Normalmente no hace falta llamarla: se autorrefresca sola.	—

🔁 Flujo de decisión

¿El usuario ya te dio un tableId/seriesCode/operationCode en un turno anterior?
  SÍ → salta directo a table_data / series_data / operation_data.
  NO → action="search" con el TEMA (ej. "índice de precios de consumo", no
       "¿cómo ha subido el IPC?"). Incluye la sigla si el usuario la dio (IPC, EPA...).

De los candidatos de "search", ¿alguno tiene matchSource="both" y nombre inequívoco?
  SÍ → úsalo con table_data (tableId).
  Hay 2+ candidatos con el MISMO tableName → compara su campo "dimensions" antes de elegir.
  Ninguno encaja del todo → prueba maxResults más alto, o un término más genérico
       (el nombre de la operación: "Encuesta de Población Activa" en vez de
       "paro juvenil en Andalucía por trimestre").

¿El usuario pide un desglose (territorio/sexo/edad/sector...)?
  SÍ, y ya tienes un tableId concreto (de "search")
       → table_dimension_values con ese tableId y el nombre de la dimensión (ej. "Municipios")
       → devuelve valueId Y variableId juntos, listo para "filters". Rápido (~1-2 s).
  SÍ, y necesitas explorar a nivel de TODA la operación (sin tabla concreta aún)
       → operation_variables SIN variableId (localizas el id de esa dimensión)
       → operation_variables CON ese variableId (localizas el id del valor exacto)
       ⚠️ Para variables con muchos valores (Municipios, ~8.000 en toda España) esto es LENTO
          (80-90 s). Prefiere table_dimension_values siempre que tengas ya un tableId.
  ⚠️ No asumas que el id sirve para cualquier tabla de la operación: ver más abajo.

¿La consulta es sobre un MUNICIPIO concreto (ej. "Vélez-Málaga")?
  Las tablas de población municipal del INE están organizadas por PROVINCIA, no por municipio.
  Busca por la PROVINCIA ("población Málaga por municipios"), no por el nombre del municipio
  — buscar directamente "población de Vélez-Málaga" no encuentra la tabla.

📥 Entrada (Input)

Campo	Tipo	Acción(es)	Descripción
action	string	todas	search | table_data | series_data | operation_variables | operation_data | refresh_catalog.
query	string	search	Tema en lenguaje natural (mejor "índice de precios de consumo" que una pregunta completa). Incluir la sigla si se conoce (IPC, EPA...) mejora mucho la precisión.
maxResults	integer	search	Máximo de tablas candidatas a devolver (por defecto 8). Súbelo si la tabla que necesitas no aparece.
tableId	string	table_data	Id numérico de tabla (campo tableId de un resultado de search). Nunca inventarlo.
seriesCode	string	series_data	Código de una serie concreta (ej. IPC251856). Suele salir del campo seriesCode de un data_point ya consultado, no de search.
operationCode	string	operation_variables, operation_data	Código alfabético de la operación (ej. IPC, EPA). Sale del campo operationCode de un resultado de search, o de la sigla si el usuario la menciona.
variableId	string	operation_variables	Id de una variable concreta, para listar sus valores posibles en vez de solo los nombres de las variables. Puede ser lento para variables con muchos valores (ver table_dimension_values).
dimension	string	table_dimension_values	Nombre de una dimensión de la tabla (campo dimensions de un resultado de search para ese tableId), ej. "Municipios". Devuelve sus valores SOLO dentro de esa tabla — mucho más rápido que operation_variables para dimensiones con muchos valores.
filters	array<string>	table_data (opcional), operation_data (obligatorio)	Pares "variableId:valorId" (ej. "115:29" = provincia de Madrid). Valor vacío tras los dos puntos ("115:") = todos los valores de esa variable. Los ids se obtienen con operation_variables/table_dimension_values, nunca se adivinan. En operation_data, incluye una variable por cada dimensión que clasifica la serie (ver errores a evitar).
periodicity	integer	operation_data (obligatoria)	1=mensual, 3=trimestral, 6=semestral, 12=anual. Sin ella, operation_data no devuelve nada aunque los filtros sean correctos.
nult	integer	table_data, series_data, operation_data	Últimos N periodos por serie (por defecto 12). Alternativo a dateFrom/dateTo.
dateFrom / dateTo	string	table_data, series_data	Rango de fechas (YYYY-MM-DD).
maxRows	integer	table_data, series_data, operation_data	Corta la salida a N filas como máximo (por defecto 500), para no desbordar tu contexto — y porque el actor cobra por resultado devuelto: prefiere acotar con filters/nult antes que subir este límite.
language	string	todas	ES (por defecto) o EN.

📤 Salida (Output)

Todos los items del dataset llevan un campo itemType que indica su forma.

search → table_candidate

{
    "itemType": "table_candidate",
    "operationCode": "IPC",
    "operationName": "Índice de Precios de Consumo (IPC)",
    "tableId": 50913,
    "tableName": "Índices por comunidades autónomas: general y de grupos ECOICOP",
    "dimensions": ["Comunidades y Ciudades Autónomas", "Grupos ECOICOP", "Tipo de dato"],
    "periodicity": "Mensual",
    "yearStart": "2002",
    "matchScore": 8.5,
    "matchSource": "both",
    "ineTableUrl": "https://www.ine.es/jaxiT3/Tabla.htm?t=50913",
    "hint": "coincide por nombre de tabla Y aparece en el buscador de texto completo del INE (alta confianza). Dimensiones: Comunidades y Ciudades Autónomas, Grupos ECOICOP, Tipo de dato. Para obtener datos de esta tabla, vuelve a llamar con action=\"table_data\" y tableId=50913. ..."
}

• matchSource: both (máxima confianza: coincide por nombre y lo confirma el buscador de texto completo) · web (solo el buscador de texto completo lo relacionó — ej. consultas como "desempleo juvenil", donde esas palabras no aparecen en ningún nombre de tabla) · catalog (solo coincidencia de nombre). Con matchSource="web" a veces matchScore es null.
• dimensions: variables por las que se puede desglosar esa tabla. Dos tablas pueden tener el tableName idéntico y solo diferenciarse aquí (ej. una versión solo nacional vs. otra con desglose territorial); cuando search detecta nombres duplicados entre los candidatos, lo avisa en hint.

search → related_document (contexto adicional, no datos)

{
    "itemType": "related_document",
    "title": "Informe enlace series de paro 1976-2000",
    "url": "https://www.ine.es/daco/daco42/daco4211/epa_reest_paro.pdf",
    "snippet": "Documento de trabajo Enlace de las series de paro 1976 2000 según la definición EPA 2002...",
    "modified": "jueves, 20 de octubre de 2005"
}

Hasta 5 notas de prensa / metodologías / fichas relacionadas con la consulta. Sin tableId/seriesCode ni datos numéricos: son contexto citable, no sustituyen a table_data/operation_data.

table_data / series_data / operation_data → data_point

Una fila por combinación serie × periodo:

{
    "itemType": "data_point",
    "seriesCode": "IPC251856",
    "seriesName": "Nacional. Índice general. Variación anual. ",
    "tableId": 50902,
    "unit": "Tasas",
    "period": "M12",
    "year": 2025,
    "date": "2025-12-01T00:00:00.000+01:00",
    "value": 2.9,
    "dataStatus": "Definitivo",
    "labels": { "Totales Territoriales": "Nacional", "Índices y Tasas": "Variación anual" },
    "ineTableUrl": null,
    "apiUrl": "https://servicios.ine.es/wstempus/js/ES/DATOS_SERIE/IPC251856?tip=AM&det=2&nult=12"
}

labels trae el desglose real de esa fila (variable → valor) — es tu forma más fiable de confirmar qué contiene la fila sin adivinar. Para citar la fuente: ineTableUrl (visor de INEbase, enlace estable) si existe, si no apiUrl.

Sin resultados → <acción>_no_results

Cuando table_data, series_data, operation_data, operation_variables o table_dimension_values no obtienen filas/valores, el run sigue terminando SUCCEEDED (no es un fallo del actor), pero el dataset nunca queda vacío en silencio: se empuja un item explicando qué pasó y qué probar a continuación, en vez de dejarlo solo en los logs del run.

{
    "itemType": "table_data_no_results",
    "tableId": "60127",
    "filters": ["141:274512"],
    "apiUrl": "https://servicios.ine.es/wstempus/js/ES/DATOS_TABLA/60127?tip=AM&det=2&nult=4&tv=141%3A274512",
    "message": "La tabla 60127 no devolvió datos para los filtros indicados (o no existe).",
    "hint": "Antes de asumir que no hay datos: (1) confirma que los filtros indicados son variableId:valueId de ESTA tabla con \"table_dimension_values\"...; (2) si los ids son correctos, prueba la misma combinación con action=\"operation_data\"..."
}

Los itemType equivalentes son series_data_no_results, operation_data_no_results, operation_variables_no_results y table_dimension_values_no_results. Trátalo como una señal para reintentar con otro action o revisar el filtro, no como "no existen esos datos en el INE": ver la nota sobre DATOS_TABLA más abajo.

operation_variables (sin variableId) → variable

{ "itemType": "variable", "operationCode": "IPC", "variableId": 115, "variableName": "Provincias", "code": "PROV" }

operation_variables (con variableId) → variable_value

{ "itemType": "variable_value", "operationCode": "IPC", "variableId": 115, "valueId": 29, "valueName": "Madrid" }

table_dimension_values → table_dimension_value

{ "itemType": "table_dimension_value", "tableId": "2882", "dimension": "Municipios", "variableId": 19, "valueId": 2632, "valueName": "Vélez-Málaga", "code": "29094", "hint": "Usa \"19:2632\" en \"filters\" de action=\"table_data\" (tableId=2882) o action=\"operation_data\"." }

A diferencia de variable_value (que sale de operation_variables, a nivel de operación), este ya trae variableId listo para usar en filters sin necesidad de otra llamada.

refresh_catalog → catalog_refresh

{ "itemType": "catalog_refresh", "operationsCount": 112, "tablesCount": 5521, "builtAt": "2026-08-12T10:00:00.000Z" }

⚠️ Errores a evitar (comprobados contra la API real)

• Nunca inventes un id. Si no lo tienes, search u operation_variables primero. Los códigos del INE son opacos: adivinarlos casi siempre falla.
• operation_data sin periodicity no devuelve nada, aunque el resto de la petición sea correcta. Rellénala siempre (1=mensual, 3=trimestral, 6=semestral, 12=anual).
• Una operación puede tener varias variables para el mismo concepto, y una tabla concreta solo usa una de ellas (comprobado en la EPA: "Edad" id 116, "Totales de edad" id 356, "Semiintervalos de edad" id 357 y "Grupos de edad" id 360 conviven en la misma operación, pero cada tabla usa solo una). operation_variables lista TODAS las variables de la operación, no las de una tabla en concreto: un id sacado de ahí puede no aplicar a la tabla que quieres filtrar, y el INE responde con un error si usas una variable que esa tabla no tiene. Forma fiable de acertar: llama a table_data con ese tableId SIN filters (o con nult=1), y mira el campo labels de las filas — ahí está el desglose real que trae la tabla.
• Dos tablas pueden compartir el mismo tableName. Compara dimensions antes de elegir entre ellas (search te avisa cuando detecta esto).
• Una misma dimensión puede mezclar DOS variables distintas. Comprobado: la tabla "Matrimonios por principales municipios..." tiene una dimensión llamada "Capitales y principales municipios" donde algunos valores son de la variable 115 (Provincias, ej. capitales de provincia) y otros de la 19 (Municipios, ej. "Vélez-Málaga"). Nunca reutilices un variableId de otra tabla o de memoria ("115 = territorio" no es una regla fija): pide siempre variableId y valueId JUNTOS de la misma llamada (table_dimension_values o operation_variables) para la tabla/operación que vas a consultar.
• Con un solo filtro, operation_data puede tardar hasta 60-70 s y terminar vacío, no solo lento (comprobado). El actor da hasta 100 s de margen para que la consulta pueda completarse en vez de fallar por timeout antes de tiempo, pero la solución real es añadir más filtros, no solo esperar.
• Filtros incompletos en operation_data no siempre devuelven "todas las combinaciones" — a veces devuelven 0 resultados, sin error, y sin que el id esté mal. Comprobado con DIR (tabla 301, "Locales por provincia, actividad y estrato"): filtrando solo Provincia + Actividad + Estrato (3 de las 5 variables que clasifican la serie) → 0 resultados; añadiendo también Condición jurídica y Tipo de dato (las 5) → 1 resultado. El actor ya compara filters contra la lista completa de variables de la operación (VARIABLES_OPERACION) y avisa por nombre de las que faltan antes de lanzar la consulta, y repite ese aviso si la respuesta viene vacía — pero la corrección (qué valor usar para cada variable que falta) sigue siendo cosa del llamante vía operation_variables.
• Tablas muy cruzadas (varias dimensiones) pueden rechazar la petición con "No puede mostrarse por restricciones de volumen" aunque el filtro y el rango de fechas sean razonables (comprobado con una tabla territorio × edad × edad × mes). El actor ya evita la causa más común (nunca manda nult y date a la vez, aunque nult tenga valor por defecto: combinarlos hace que el INE rechace tablas que con cualquiera de los dos por separado responden bien), pero si sigue pasando, añade un filters que acote al menos una dimensión más (table_dimension_values).
• DATOS_TABLA (table_data) puede devolver, de forma puntual y transitoria, HTTP 200 con el cuerpo vacío para un filtro perfectamente válido — no es que esa combinación no tenga datos (comprobado repitiendo la misma petición segundos después: la segunda vez responde bien). El actor ya reintenta automáticamente cuando detecta esto (ineApi.js), pero si el reintento se agota, table_data empuja un item table_data_no_results en vez de terminar en silencio con 0 items — nunca lo interpretes como "esta variable no existe en la tabla" sin antes probar de nuevo o, si conoces el operationCode, con operation_data sobre el mismo filtro.
• search no siempre coloca la tabla más general en primer lugar. El matching pondera las palabras según lo distintivas que son en el catálogo (ej. "turistas" pesa más que "extranjero", que aparece en cientos de tablas de temas distintos), pero sigue siendo texto, no comprensión semántica. Cuando una consulta combina varias palabras comunes que por casualidad coinciden con otra tabla no relacionada, esa puede rankear más alto. Revisa 2-3 candidatos, no asumas ciegamente el primero — usa tableName, dimensions y matchSource para decidir.
• operation_data con menos filtros de los necesarios NO da error, pero el resultado es impredecible: puede tardar 30-40 s y devolver miles de series sin filtrar (comprobado con el IPC: un solo filtro de provincia, sin el grupo ECOICOP, tarda ~34 s), o puede devolver 0 resultados directamente (comprobado con DIR: 3 de sus 5 variables clasificadoras → 0 resultados; las 5 → 1 resultado). Ninguno de los dos casos es un fallo del actor — es una consecuencia de no incluir un filtro por cada variable que clasifica la serie. El actor compara filters contra VARIABLES_OPERACION y avisa por nombre de las variables que faltan antes de consultar (y de nuevo si la respuesta viene vacía), pero la señal más fiable sigue siendo mirar tú mismo cuántas variables tiene la operación con operation_variables.
• Para dimensiones con muchos valores (Municipios y similares), usa table_dimension_values, no operation_variables. operation_variables con variableId de una variable como "Municipios" consulta TODA España (~8.000 valores) y el propio servidor del INE tarda 80-90 s en responder — comprobado, no es un problema de red puntual, es reproducible. Si ya tienes un tableId (de search), table_dimension_values consulta solo los valores DENTRO de esa tabla (ej. los ~100 municipios de una provincia) y responde en 1-2 s.
• Los municipios se buscan por provincia, no por su propio nombre. Las tablas de población municipal del INE están organizadas una por provincia (ej. "Málaga: Población por municipios y sexo"); buscar "población de Vélez-Málaga" no encuentra nada porque ningún nombre de tabla menciona ese municipio. Busca por la provincia ("población Málaga por municipios") y usa table_dimension_values para localizar el municipio concreto dentro de esa tabla.
• Cita siempre la fuente con ineTableUrl o apiUrl al construir una respuesta con estos datos.
• No todo lo que hay en INEbase está en Tempus3. Comprobado: no existe ninguna operación de comercio exterior de bienes (exportaciones/importaciones) en la API; si el usuario pide eso, dilo explícitamente en vez de devolver una tabla aproximada (ej. de Contabilidad Nacional) sin avisar. Antes de asumir que un tema no está cubierto, prueba search con 2-3 formulaciones distintas.
• Algunos desgloses solo se llegan por operation_variables, no por search. Ej. "IPC de alimentos": ninguna tabla del IPC se llama "alimentos" en su nombre (esa categoría es un VALOR dentro de la variable "Grupos ECOICOP", no el nombre de una tabla), así que search no la encuentra directamente — hay que buscar la tabla general del IPC y filtrar por ese valor con operation_variables/filters.

🤖 Ejemplos de flujo (lenguaje natural → acciones)

El usuario pide...	Secuencia de acciones
"¿Cómo ha evolucionado el IPC general en España?"	search (query="Índice de Precios de Consumo") → table_data (tableId de "Índice general nacional")
"Dame la última tasa de paro"	search (query="Encuesta de Población Activa tasa de paro") → table_data con nult=1
"Población de Vélez-Málaga en los últimos 10 años"	search (query="población Málaga por municipios" — por la provincia, no por el municipio) → candidato con dimensions: ["Municipios", "Sexo"] → table_dimension_values (tableId, dimension="Municipios") para el id de "Vélez-Málaga" → table_data con filters=["19:<id>"] y nult=10
"¿Cómo está el desempleo juvenil?"	search (query="desempleo juvenil") → ninguna tabla se llama así, pero el buscador de texto completo del INE relaciona la consulta con la EPA (matchSource="web") y devuelve la tabla "Tasas de paro por distintos grupos de edad, sexo y comunidad autónoma" → operation_variables para el id del grupo de edad joven → operation_data con ese filtro
"Compara el PIB de España y la UE"	search (query="Producto Interior Bruto") → si los candidatos no cubren la comparativa UE, dilo explícitamente en vez de improvisar un dato

📝 Notas técnicas

• El catálogo (operaciones + tablas) se cachea y persiste entre ejecuciones del actor; se autorrefresca cada 7 días. Tiempos medidos contra el servicio real: catálogo en frío ~20-25 s (solo la 1ª vez o tras 7 días); search con caché ~2-3 s; table_data/series_data/operation_variables (variable normal) ~1-1,5 s; table_dimension_values ~1-2 s; operation_data bien filtrado ~1,5-5 s.
• Dos operaciones son lentas por diseño, no por fallo: operation_variables con una variable de muchos valores (Municipios, ~8.000 en toda España) puede tardar 80-90 s — usa table_dimension_values en su lugar siempre que tengas un tableId. operation_data con menos filtros de los que clasifican la serie puede tardar 30-40 s (devuelve todas las combinaciones sin filtrar en vez de fallar). El actor da más margen de tiempo a estas dos llamadas específicamente (hasta 60-100 s) y avisa cuando detecta el caso de un solo filtro, en vez de agotar el tiempo de espera en 3 reintentos cortos sin nunca completarse (~45 s) como ocurría antes.
• Todas las llamadas de datos piden a Tempus3 salida amigable + metadatos (etiquetas legibles, no solo códigos numéricos).
• action="search" combina el catálogo con una consulta al buscador de texto completo de INEbase; si esa consulta falla, search sigue funcionando solo con el catálogo (no rompe la ejecución).