Taules. API 
El servei Taules retorna dades i metadades d'un conjunt creixent d'estadístiques de l'Idescat.
La utilització d'aquest servei comporta l'acceptació de les condicions d'ús de les APIs de l'Idescat.
| URI base | https://api.idescat.cat/taules/v2/{estadística}/{node}/{taula}/{geo}[/data][?{filtres}] |
|---|---|
| Mètodes HTTP | GET, POST |
| Format de la resposta | json (JSON-stat) |
| Versió | 2.00 (18/9/2023) |
1. Petició
1.1 Estadístiques disponibles
https://api.idescat.cat/taules/v2
Retorna la llista d'estadístiques disponibles a través de l'API com una col·lecció JSON-stat.
1.2 Nodes disponibles
https://api.idescat.cat/taules/v2 /{estadística}
Retorna la llista de nodes disponibles d'una estadística com una col·lecció JSON-stat.
Ex. 1: Nodes de l'estadística PMH (Padró municipal d'habitants)
https://api.idescat.cat/taules/v2 /pmh
1.3 Taules disponibles
https://api.idescat.cat/taules
Retorna la llista de taules disponibles en un determinat node d'una estadística com una col·lecció JSON-stat.
Ex. 2: Taules del node 1180 ("Població a 1 de gener. Per sexe i edat any a any") de l'estadística PMH (Padró municipal d'habitants)
https://api.idescat.cat/taules/v2 /pmh /1180
1.4 Divisions territorials disponibles
https://api.idescat.cat/taules/v2 /{estadística} /{node} /{taula}
Retorna la llista de divisions territorials disponibles per a una determinada taula com una col·lecció JSON-stat.
Ex. 3: Divisions territorials de la taula 8078 ("Població a 1 de gener. Per sexe i edat any a any (2014–)") del node 1180 de l'estadística PMH (Padró municipal d'habitants)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078
1.5 Metadades d'una taula
https://api.idescat.cat/taules/v2 /{estadística} /{node} /{taula} /{geo}
Retorna les metadades d'una taula per a una determinada divisió territorial com un conjunt de dades JSON-stat.
Ex. 4: Metadades de la taula 8078 ("Població a 1 de gener. Per sexe i edat any a any (2014–)") per comarques i Aran del node 1180 de l'estadística PMH (Padró municipal d'habitants)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com
La resposta d'aquesta petició és idèntica a la petició de dades, excepte en el fet que no conté dades.
La petició de les dades de la taula s'exposa en l'element la propietat describes.
1.6 Dades d'una taula
https://api.idescat.cat/taules/v2 /{estadística} /{node} /{taula} /{geo} /data
Retorna les dades i les metadades d'una taula per a una determinada divisió territorial com un conjunt de dades JSON-stat.
L'API no permet recuperar més de 10.000 20.000 dades en una única crida. Consulteu la secció 1.7 per conèixer com filtrar el nombre de cel·les retornat.
Ex. 5: Metadades de la taula 8078 ("Població a 1 de gener. Per sexe i edat any a any (2014–)") per comarques i Aran del node 1180 de l'estadística PMH (Padró municipal d'habitants)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data
La petició només de les metadades de la taula s'exposa en la propietat describedby.
1.7 Paràmetres
1.7.1 El paràmetre general lang
Totes les crides admeten el paràmetre lang per determinar l'idioma de la resposta. Aquest paràmetre admet tres valors: ca (valor per defecte), es i en.
Ex. 6: Nodes de l'estadística PMH (Padró municipal d'habitants) en anglès
https://api.idescat.cat/taules/v2 /pmh ?lang=en
1.7.2 Filtres
Quan es recuperen dades o metadades és possible filtrar categories de les dimensions de la taula. Per a això, cal conèixer el nom de les categories i de les dimensions, tal com apareixen en la petició de metadades descrita a la secció 1.5. En el cas de les dimensions que apareguin com a paràmetres a la crida, només es recuperaran les categories que es passin com a valors separats per comes.
Ex. 7: Població femenina per edat any a any a l'Alt Camp i al conjunt de Catalunya
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01,TOTAL
Ex. 8: Població femenina per edat any a any a l'Alt Camp el 2020 i el 2021
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01&YEAR=2020,2021
Per tal d'evitar la limitació que imposa el protocol HTTP/1.1 a les adreces, aquesta API admet excepcionalment el mètode POST: només s'ha d'utilitzar aquest mètode quan la complexitat dels filtres donaria lloc a una adreça de les peticions GET superior als 2.000 caràcters. Exemple:
Adreça: https://api.idescat.cat/taules
Cos del missatge: SEX=F&COM=01,
1.7.3 El paràmetre temporal _LAST_
A més de filtrar les dades especificant els valors que es volen de la dimensió temporal, és possible fer-ho proporcionant el nombre de darrers períodes que es volen.
Ex. 9: Població femenina per edat any a any a l'Alt Camp en els darrers dos anys disponibles
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01&_LAST_=2
2. Resposta
2.1 Classes
L'API retorna respostes de classe col·lecció (JSON-stat collection), conjunt de dades (JSON-stat dataset) i error. Per a les dues primeres, consulteu la documentació de JSON-stat.
Quan es produeix un error, la resposta pren la següent forma:
{
version: "2.0",
class: "error",
status: "{Codi d'estat HTTP}",
id: "{Codi d'error intern}",
label: "{Text explicatiu}"
}
Per exemple, quan se supera el límit de nombre de dades, l'API retorna:
{
version: "2.0",
class: "error",
status: "416",
id: "05",
label: "Nombre màxim de dades superat."
}
| Codi intern | Descripció | Codi d'estat HTTP |
|---|---|---|
| 01 | Identificador d'estadística incorrecte. | 400 |
| 02 | Identificador de node incorrecte. | 400 |
| 03 | Identificador de taula incorrecte. | 400 |
| 04 | Identificador de divisió territorial incorrecte. | 400 |
| 05 | Nombre màxim de dades superat. | 416 |
| 06 | Valor del paràmetre _LAST_ incorrecte. | 400 |
| 00 | Error greu de l'API. | 500 |
2.2 Extensions
JSON-stat suporta la personalització de la resposta utilitzant la propietat extension, ja sigui associant-la al conjunt de dades o a una dimensió específica. L'API fa ús d'aquesta propietat en diferents situacions.
2.2.1 Estat
La propietat status associa un símbol (per exemple, "p") als valors amb algun estat especial. L'API utilitza una extensió a nivell de conjunt de dades per associar un text (per exemple, "Dada provisional") als símbols utilitzats.
"extension": {
"status": {
"label": {
"p": "Dada provisional"
}
}
}
De vegades, la imputació d'un estat a un valor es deriva de l'estat associat a una categoria d'una dimensió. Per exemple, la provisionalitat de les dades sovint està associada a un determinat període temporal. L'API utilitza una extensió a nivell de dimensió per associar un estat a algunes de les seves categories.
"extension": {
"status": {
"2022": "p"
}
}
2.2.2 Fonts
A més d'utilitzar la propietat source de JSON-stat (text), l'API retorna un vector amb les diferents fonts associades a la taula com a extensió del conjunt de dades.
"extension": {
"source": [
"Idescat, a partir del Padró continu de l'INE."
]
}
2.2.3 Canvis en la dimensió geogràfica
Les dimensions amb rol geogràfic identifiquen la granularitat de la divisió territorial utilitzada, per exemple: "comarcal" (COM), "municipal" (MUN), etc. La versió de la divisió territorial i els possibles canvis que s'hi hagin introduït s'exposen en una extensió associada a la dimensió geogràfica en qüestió.
"COM" :
"label" : "comarca o Aran",
"extension" : {
"break" : [ {
"time" : "2010",
"id" : "COM41",
"label" : "Comarques vigents en data 17/01/1990"
}, {
"time" : "2015",
"id" : "COM42",
"label" : "Comarques vigents en data 01/05/2015"
} ]
}
}
Per a l'identificador del període inicial d'aplicació d'una nova versió de la divisió territorial, s'indica l'identificador intern de la classificació geogràfica i un text descriptiu. La propietat time indica la categoria de la primera dimensió amb un rol temporal.
2.2.4 Altres extensions
En el futur podrien afegir-se altres extensions a la resposta, que s'inclouran pertinentment en aquesta documentació. Vegeu també 2.3.3 Peticions relacionades.
2.3 Enllaços
JSON-stat utilitza la propietat link per oferir enllaços relacionats amb la crida a l'API, agrupats per relacions. Quan els enllaços retornen respostes en format JSON-stat, s'exposen tres propietats JSON-stat: class, href i label. Quan no és així, l'API exposa dues propietats: type (tipus de contingut) i href.
2.3.1 Dades i metadades
La vinculació entre metadades i les seves dades s'exposa en la propietat describes.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com",
"link" : {
"describes" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com/data",
"label" : "Població a 1 de gener. Per sexe. Comarques i Aran"
} ],
…
},
…
}
La vinculació entre dades i les seves metadades s'exposa en la propietat describedby.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com/data",
"link" : {
"describedby" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com",
"label" : "Població a 1 de gener. Per sexe. Comarques i Aran"
} ],
…
},
…
}
2.3.2 Rectificacions
La informació sobre possibles rectificacions recents que s'hagin introduït en les dades s'exposa en la propietat monitor.
"link" : {
"monitor" : [ {
"type" : "application/json",
"href" : "https://api.idescat.cat/rectificacions/v1/rectificacions/cerca.json?id=485"
} ],
…
}
Aquest enllaç amb l'API de Rectificacions pot incloure una rectificació o més d'una.
2.3.3 Peticions relacionades
Altres peticions relacionades s'exposen amb propietats de tipus related. En aquest apartat es poden trobar les crides a les metadades de la mateixa taula per a diferents divisions territorials (mateix identificador de node, mateix identificador de taula, identificador geogràfic diferent):
"related" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/prov",
"label" : "Població a 1 de gener. Per sexe. Províncies"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/at",
"label" : "Població a 1 de gener. Per sexe. Àmbits del Pla territorial"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com",
"label" : "Població a 1 de gener. Per sexe. Comarques i Aran"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/mun",
"label" : "Població a 1 de gener. Per sexe. Municipis"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/ac",
"label" : "Població a 1 de gener. Per sexe. Per agrupacions censals"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/dis",
"label" : "Població a 1 de gener. Per sexe. Districtes censals"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/sec",
"label" : "Població a 1 de gener. Per sexe. Seccions censals"
} ]
També s'hi poden trobar les crides a les metadades de les diferents taules que el mateix node ha tingut al llarg del temps (mateix identificador de node, identificador de taula diferent, mateix identificador geogràfic):
{
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/censph/10/1/cat",
"label" : "Població. Per sexe i edat any a any. Catalunya (1981–2001)"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/censph/10/5464/cat",
"label" : "Població. Per sexe i edat any a any. Catalunya (1975)"
}
Excepcionalment, poden compartir identificador de node taules de naturalesa diferent que acostumen a presentar-se conjuntament. Aquest cas es pot distingir de l'anterior gràcies a l'existència d'una extensió group amb valor true.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15840/cat/data",
"link" : {
"describedby" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15840/cat",
"label" : "Producte interior brut a preus corrents. Oferta. Dades corregides d'estacionalitat. Catalunya"
} ],
"related" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15841/cat",
"label" : "Producte interior brut a preus corrents. Demanda. Dades corregides d'estacionalitat. Catalunya",
"extension" : {
"group" : true
}
} ]
},
…
}
2.3.4 Altres enllaços
En el futur podrien afegir-se altres enllaços a la resposta, que s'inclouran pertinentment en aquesta documentació.