Tablas. API 
El servicio Tablas retorna datos y metadatos de un conjunto creciente de estadísticas del Idescat.
La utilización de este servicio comporta la aceptación de las condiciones de uso de las API del Idescat.
| URI base | https://api.idescat.cat/taules/v2/{estadística}/{nodo}/{tabla}/{geo}[/data][?{filtros}] |
|---|---|
| Métodos HTTP | GET, POST |
| Formatos de la respuesta | json (JSON-stat) |
| Versión | 2.00 (18/9/2023) |
1. Petición
1.1 Estadísticas disponibles
https://api.idescat.cat/taules/v2
Retorna la lista de estadísticas disponibles a través de la API como una colección JSON- stat.
1.2 Nodos disponibles
https://api.idescat.cat/taules/v2 /{estadística}
Retorna la lista de nodos disponibles de una estadística como una colección JSON-stat.
Ej. 1: Nodos de la estadística PMH (Padrón municipal de habitantes)
https://api.idescat.cat/taules/v2 /pmh
1.3 Tablas disponibles
https://api.idescat.cat/taules
Retorna la lista de tablas disponibles en un determinado nodo de una estadística como una colección JSON-stat.
Ej. 2: Tablas del nodo 1180 ("Población a 1 de enero. Por sexo y edad año a año") de la estadística PMH (Padrón municipal de habitantes)
https://api.idescat.cat/taules/v2 /pmh /1180
1.4 Divisiones territoriales disponibles
https://api.idescat.cat/taules/v2 /{estadística} /{nodo} /{tabla}
Retorna la lista de divisiones territoriales disponibles para una determinada tabla como una colección JSON-stat.
Ej. 3: Divisiones territoriales de la tabla 8078 ("Población a 1 de enero. Por sexo y edad año a año (2014–)") del nodo 1180 de la estadística PMH (Padrón municipal de habitantes)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078
1.5 Metadatos de una tabla
https://api.idescat.cat/taules/v2 /{estadística} /{nodo} /{tabla} /{geo}
Retorna los metadatos de una tabla para una determinada división territorial como un conjunto de datos JSON-stat.
Ej. 4: Metadatos de la tabla 8078 ("Población a 1 de enero. Por sexo y edad año a año (2014–)") por comarcas y Aran del nodo 1180 de la estadística PMH (Padrón municipal de habitantes)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com
La respuesta de esta petición es idéntica a la petición de datos, salvo que no contiene datos.
La petición de los datos de la tabla se expone en la propiedad describes.
1.6 Datos de una tabla
https://api.idescat.cat/taules/v2 /{estadística} /{nodo} /{tabla} /{geo} /data
Retorna los datos y metadatos de una tabla para una determinada división territorial como un conjunto de datos JSON-stat.
La API no permite recuperar más de 10.000 20.000 datos en una única llamada. Consulte la sección 1.7 para conocer cómo filtrar el número de celdas retornado.
Ej. 5: Metadatos de la tabla 8078 ("Población a 1 de enero. Por sexo y edad año a año (2014–)") por comarcas y Aran del nodo 1180 de la estadística PMH (Padrón municipal de habitantes)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data
La petición solo de los metadatos de la tabla se expone en la propiedad describedby.
1.7 Parámetros
1.7.1 El parámetro general lang
Todas las llamadas admiten el parámetro lang para determinar el idioma de la respuesta. Este parámetro admite tres valores: ca (valor por defecto), es y en.
Ej. 6: Nodos de la estadística PMH (Padrón municipal de habitantes) en inglés
https://api.idescat.cat/taules/v2 /pmh ?lang=en
1.7.2 Filtros
Cuando se recuperan datos o metadatos es posible filtrar categorías de las dimensiones de la tabla. Para ello, es necesario conocer el nombre de las categorías y de las dimensiones, tal y como aparecen en la petición de metadatos descrita en la sección 1.5. En el caso de las dimensiones que aparezcan como parámetros en la llamada, sólo se recuperarán las categorías que se pasen como valores separados por comas.
Ej. 7: Población femenina por edad año a año en L'Alt Camp y en el conjunto de Cataluña
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01,TOTAL
Ej. 8: Población femenina por edad año a año en L'Alt Camp en 2020 y 2021
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01&YEAR=2020,2021
Para evitar la limitación que impone el protocolo HTTP/1.1 a las direcciones, esta API admite excepcionalmente el método POST: solo se debe utilizar este método cuando la complejidad de los filtros daría lugar a una dirección de las peticiones GET superior a los 2.000 caracteres. Ejemplo:
Dirección: https://api.idescat.cat/taules
Cuerpo del mensaje: SEX=F&COM=01,
1.7.3 El parámetro temporal _LAST_
Además de filtrar los datos especificando los valores que se quieren de la dimensión temporal, es posible hacerlo proporcionando el número de últimos períodos que se desean.
Ej. 9: Población femenina por edad año a año en L'Alt Camp en los últimos dos años disponibles
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01&_LAST_=2
2. Respuesta
2.1 Clases
La API retorna respuestas de clase colección (JSON-stat collection), conjunto de datos (JSON-stat dataset ) y error. Para las dos primeras, consulte la documentación de JSON-stat.
Cuando se produce un error, la respuesta toma la siguiente forma:
{
version: "2.0",
class: "error",
status: "{Código de estado HTTP}",
id: "{Código de error interno}",
label: "{Texto explicativo}"
}
Por ejemplo, cuando se supera el límite de número de datos, la API retorna:
{
version: "2.0",
class: "error",
status: "416",
id: "05",
label: "Número máximo de datos superado."
}
| Código interno | Descripción | Código de estado HTTP |
|---|---|---|
| 01 | Identificador de estadística incorrecto. | 400 |
| 02 | Identificador de nodo incorrecto. | 400 |
| 03 | Identificador de tabla incorrecto. | 400 |
| 04 | Identificador de división territorial incorrecto. | 400 |
| 05 | Número máximo de datos superado. | 416 |
| 06 | Valor del parámetro _LAST_ incorrecto. | 400 |
| 00 | Error grave de la API. | 500 |
2.2 Extensiones
JSON-stat soporta la personalización de la respuesta utilizando la propiedad extension, ya sea asociándola al conjunto de datos o a una dimensión específica. La API utiliza esta propiedad en diferentes situaciones.
2.2.1 Estado
La propiedad status asocia un símbolo (por ejemplo, "p") a los valores con algún estado especial. La API utiliza una extensión a nivel de conjunto de datos para asociar un texto (por ejemplo, "Dato provisional") a los símbolos utilizados.
"extension": {
"status": {
"label": {
"p": "Dato provisional"
}
}
}
En ocasiones, la imputación de un estado a un valor se deriva del estado asociado a una categoría de una dimensión. Por ejemplo, la provisionalidad de los datos a menudo está asociada a un determinado período temporal. La API utiliza una extensión a nivel de dimensión para asociar un estado a algunas de sus categorías.
"extension": {
"status": {
"2022": "p"
}
}
2.2.2 Fuentes
Además de utilizar la propiedad source de JSON-stat (texto), la API retorna un vector con las diferentes fuentes asociadas a la tabla como extensión del conjunto de datos.
"extension": {
"source": [
"Idescat, a partir del Padrón continuo del INE."
]
}
2.2.3 Cambios en la dimensión geográfica
Las dimensiones con rol geográfico identifican la granularidad de la división territorial utilizada, por ejemplo: "comarcal" (COM), "municipal" (MUN), etc. La versión de la división territorial y los posibles cambios que se hayan introducido se exponen en una extensión asociada a la dimensión geográfica en cuestión.
"COM" :
"label" : "comarca o Aran",
"extension" : {
"break" : [ {
"time" : "2010",
"id" : "COM41",
"label" : "Comarcas vigentes en fecha 17/01/1990"
}, {
"time" : "2015",
"id" : "COM42",
"label" : "Comarcas vigentes en fecha 01/05/2015"
} ]
}
}
Para el identificador del período inicial de aplicación de una nueva versión de la división territorial, se indica el identificador interno de la clasificación geográfica y un texto descriptivo. La propiedad time indica la categoría de la primera dimensión con un rol temporal.
2.2.4 Otras extensiones
En el futuro podrían añadirse otras extensiones a la respuesta, que se incluirán pertinentemente en esta documentación. Véase también 2.3.3 Peticiones relacionadas.
2.3 Enlaces
JSON-stat utiliza la propiedad link para ofrecer enlaces relacionados con la llamada a la API, agrupados por relaciones. Cuando los enlaces devuelven respuestas en formato JSON-stat, se exponen tres propiedades JSON-stat: class, href y label. Cuando no es así, la API expone dos propiedades: type (tipo de contenido) y href.
2.3.1 Datos y metadatos
La vinculación entre metadatos y sus datos se expone en la propiedad describes.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com?lang=es",
"link" : {
"describes" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com/data?lang=es",
"label" : "Población a 1 de enero. Por sexo. Comarcas y Aran"
} ],
…
},
…
}
La vinculación entre datos y sus metadatos se expone en la propiedad describedby.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com/data?lang=es",
"link" : {
"describedby" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/comlang=es",
"label" : "Población a 1 de enero. Por sexo. Comarcas y Aran"
} ],
…
},
…
}
2.3.2 Rectificaciones
La información sobre posibles rectificaciones recientes que se hayan introducido en los datos se expone con la propiedad monitor.
"link" : {
"monitor" : [ {
"type" : "application/json",
"href" : "https://api.idescat.cat/rectificacions/v1/rectificacions/cerca.json?id=485&lang=es"
} ],
…
}
Este enlace con la API de Rectificaciones puede incluir una o más rectificaciones.
2.3.3 Peticiones relacionadas
Otras peticiones relacionadas se exponen con propiedades de tipo related. En este apartado se pueden encontrar las llamadas a los metadatos de la misma tabla para diferentes divisiones territoriales (mismo identificador de nodo, mismo identificador de tabla, diferente identificador geográfico):
"related" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/prov?lang=es",
"label" : "Población a 1 de enero. Por sexo. Provincias"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/at?lang=es",
"label" : "Población a 1 de enero. Por sexo. Ámbitos del Plan territorial"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com?lang=es",
"label" : "Población a 1 de enero. Por sexo. Comarcas y Aran"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/mun?lang=es",
"label" : "Población a 1 de enero. Por sexo. Municipios"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/ac?lang=es",
"label" : "Población a 1 de enero. Por sexo. Por agrupaciones censales"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/dis?lang=es",
"label" : "Población a 1 de enero. Por sexo. Distritos censales"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/sec?lang=es",
"label" : "Población a 1 de enero. Por sexo. Secciones censales"
} ]
También se pueden encontrar las llamadas a los metadatos de las diferentes tablas que el mismo nodo ha tenido a lo largo del tiempo (mismo identificador de nodo, diferente identificador de tabla, mismo identificador geográfico):
{
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/censph/10/1/cat?lang=es",
"label" : "Población. Por sexo y edad año a año. Cataluña (1981–2001)"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/censph/10/5464/cat?lang=es",
"label" : "Población. Por sexo y edad año a año. Cataluña (1975)"
}
Excepcionalmente, pueden compartir identificador de nodo tablas de diferente naturaleza que suelen presentarse conjuntamente. Este caso puede distinguirse del anterior gracias a la existencia de una extensión group con valor true.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15840/cat/data?lang=es",
"link" : {
"describedby" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15840/cat?lang=es",
"label" : "Producto interior bruto a precios corrientes. Oferta. Datos corregidos de estacionalidad. Cataluña"
} ],
"related" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15841/cat?lang=es",
"label" : "Producto interior bruto a precios corrientes. Demanda. Datos corregidos de estacionalidad. Cataluña",
"extension" : {
"group" : true
}
} ]
},
…
}
2.3.4 Otros enlaces
En el futuro podrían añadirse otros enlaces a la respuesta, que se incluirán pertinentemente en esta documentación.