Interfície de programació d'aplicacions (API)
L'Idescat exposa part de les seves dades a través d'una col·lecció d'APIs de tipus REST (RESTful Web Services). Les APIs de l'Idescat ofereixen mètodes perquè els programes de tercers puguin obtenir informació de l'Institut d'Estadística de Catalunya i integrar-la en altres serveis. La utilització de qualsevol de les APIs de l'Idescat comporta l'acceptació de les condicions d'ús del servei.
| URI base | https://api.idescat.cat/{servei}/v{versió principal}/{operació}.{format}[?paràmetres] |
|---|---|
| Mètode HTTP | GET |
| Formats de la resposta | xml, json, php |
| Versió | 1.00 (14/12/2009) |
| Dreceres | Petició, Resposta |
APIs disponibles
Condicions d'ús
- Heu de reconèixer l'origen de les dades, ja sigui utilitzant els enllaços que proporcionin les APIs, ja sigui enllaçant amb Idescat.cat.
- No esteu autoritzat a mostrar el contingut proporcionat per les APIs de manera que no permeti accedir als enllaços amb les pàgines de l'Idescat. Tampoc esteu autoritzat a incloure en un marc (<frame>, <iframe>) cap pàgina web de l'Idescat.
- En presentar-los, no esteu autoritzat a modificar o editar les dades, metadades o enllaços proporcionats per les APIs.
- Heu d'assegurar que el sentit del contingut proporcionat per les APIs no es canvia o distorsiona.
- L'ús de les APIs de l'Idescat no suposa cap tipus de suport, relació o afiliació entre el servei que les utilitza i l'Institut d'Estadística de Catalunya. No esteu autoritzat a mostrar la informació proporcionada per les APIs de l'Idescat de tal manera que se suggereixi aquest suport, relació o afiliació.
- L'Idescat es reserva el dret de limitar les peticions repetides des d'un mateix origen per garantir l'accés al servei per a tothom. És la vostra responsabilitat emprar els mecanismes necessaris per evitar peticions de la mateixa informació en espais de temps curt. L'ús excessiu pot ocasionar la finalització del servei. Si penseu fer un ús intensiu de les APIs de l'Idescat poseu-vos en contacte amb l'Idescat per tal de poder garantir que aquest ús no perjudicarà la disponibilitat general del servei.
- La cessió, utilització o explotació de les APIs hauran de complir les estipulacions contingudes en la legislació vigent i sempre es vincularan a usos legítims.
- En cas de vulnerar aquestes condicions, l'Idescat es reserva el dret de desactivar el vostre accés a les APIs. Així mateix, també sereu responsables dels danys que pugui suposar l'explotació indeguda d'aquesta informació.
- L'Idescat es reserva el dret de modificar discrecionalment aquestes condicions en qualsevol moment, així com de finalitzar aquesta relació i cancel·lar-ne l'ús, i declina qualsevol garantia expressa o implícita relacionada amb aquest servei.
1. Petició
1.1. Anatomia de les peticions
Tota petició ha d'especificar obligatòriament un servei, la versió principal del servei, una operació vàlida per aquest servei i un format de resposta. Opcionalment, es poden especificar un seguit de paràmetres generals i específics del servei.
https://api.idescat.cat/{servei}
Alguns serveis poden compartir la sintaxi de les peticions i l'estructura de les respostes. Aquests són tractats com un únic servei que disposa de subserveis. En aquest cas, la forma de la petició és:
https://api.idescat.cat/{servei}
Tot i que aquesta és la forma en la qual internament són tractades totes les peticions, les APIs també solen admetre una sintaxi externa més amigable que no requereix especificar una operació (vegeu Invocació sense operació).
1.1.1. Servei i versió
Cada servei disposa d'un identificador, d'una versió i d'uns paràmetres específics. Per exemple, el servei d'Indicadors al dia s'identifica amb el valor indicadors i només disposa d'una versió (1).
Ex. 1: Petició a la versió 1 del servei d'Indicadors al dia
https://api.idescat.cat/indicadors/v1 /{…}
Els serveis poden tenir diferents versions principals, incompatibles entre elles. Les millores incrementals no afecten la versió principal (per exemple, 1.01 respecte a 1.00) i, per tant, tampoc la petició.
1.1.2. Operació
Els serveis solen suportar una diversitat d'operacions. Per exemple, el servei indicadors admet l'operació dades, que retorna resultats estadístics, però també l'operació nodes.
Ex. 2: Dues peticions al mateix servei però a operacions diferents
https://api.idescat.cat/indicadors/v1 /dades.{…}
https://api.idescat.cat/indicadors/v1 /nodes.{…}
El servei i l'operació determinen l'estructura del document retornat.
1.1.3. Format
Determina el format de la resposta. Admet tres valors amb caràcter general:
- xml: retorna el resultat en format eXtensible Markup Language.
- json: retorna el resultat en format JavaScript Object Notation. Permet especificar una funció de devolució amb el paràmetre callback amb el nom de la funció. Tot i que JSON és una cadena codificada en UTF-8, per conveniència, la sortida en aquest format té en compte el valor especificat a enc.
- php: retorna el resultat en format PHP serialitzat. Aquesta sortida té la mateixa estructura que la sortida en format JSON: es tracta d'una cadena que pot ser desserialitzada per crear un objecte (no una matriu) PHP. En aquest cas, el resultat sempre es retorna codificat en UTF-8 amb independència del valor d'enc.
Ex. 3: Diverses peticions amb resposta en diferents formats
https://api.idescat.cat/indicadors/v1 /dades.xml
https://api.idescat.cat/indicadors/v1 /dades.php
https://api.idescat.cat/indicadors/v1 /dades.json
https://api.idescat.cat/indicadors/v1 /dades.json ?callback=f
1.2. Paràmetres generals
Tota petició té uns paràmetres generals (comuns a tots els serveis) i uns paràmetres específics del servei, documentats a l'API del servei.
1.2.1. Idioma de la resposta (lang)
Admet tres valors:
- ca: català (valor per defecte)
- es: castellà
- en: anglès
Ex. 4: Resultat en castellà
https://api.idescat.cat/indicadors/v1 /dades.xml ?lang=es
1.2.2. Codificació de la resposta (enc)
Aquest paràmetre admet dos valors: utf-8 (valor per defecte) i iso-8859-1.
Ex. 5: Resultat codificat en ISO-8859-1
https://api.idescat.cat/indicadors/v1 /dades.xml ?enc=iso-8859-1
Si el format de la resposta és php la codificació és UTF-8, sigui quin sigui el valor d'enc.
1.3. Paràmetres específics
A més dels paràmetres generals descrits a l'apartat anterior, cada servei admet uns paràmetres específics ("variables") que permeten configurar la informació obtinguda. Aquests paràmetres estan documentats a l'API del servei.
Per exemple, l'operació dades del servei indicadors permet seleccionar el nombre d'indicadors obtinguts gràcies als paràmetres tt, max i min.
Ex. 6: Paràmetres específics
https://api.idescat.cat/indicadors/v1 /dades.xml ?tt=10 &max=10 &min=3
1.3.1. El paràmetre general p
Les variables del servei (o "paràmetres específics") poden encapsular-se en un paràmetre general per efectuar una crida més compacta. Per fer-ho cal incloure un seguit de parelles variable/valor separades per punts i coma.
Ex. 7: Peticions sinònimes
https://api.idescat.cat/indicadors/v1 /dades.json ?tt=10 &max=10 &min=3
https://api.idescat.cat/indicadors/v1 /dades.json ?p=tt/10;max/10;min/3
1.4. Invocació sense operació
Per raons d'amigabilitat, algunes APIs poden admetre peticions amb una sintaxi que no requereix especificar una de les operacions generals previstes. En el seu lloc, s'utilitzen referències a recursos que solen ser específics de cada API. Consulteu la documentació de cada API per saber si la invocació sense operació està disponible i per conèixer la seva sintaxi específica.
Com que internament les APIs utilitzen sempre la invocació amb operació, els missatges d'error inclouen les peticions en aquesta forma, amb independència de com van ser especificades per l'usuari.
2. Resposta
2.1. Codis de resposta i errors
En cas que el servidor no pugui atendre la petició, el codi retornat serà 500 (Server Error) o 503 (Service Unavailable). En la resta de casos, podem distingir dos tipus de petició que retornen diferents codis de resposta HTTP:
- Correcta: retorna el codi de resposta 200 (OK).
- Incorrecta: retorna el codi de resposta 400 (Bad Request). Com que alguns clients intercepten el contingut de la resposta quan el codi és d'error, per conveniència es pot forçar el codi 200 (OK) afegint a la petició el paràmetre rc amb valor 200 (aquest paràmetre s'ignorarà si s'especifica un altre valor).
En el cas de petició incorrecta, el document retornat contindrà el codi d'error (id), un text explicatiu en l'idioma sol·licitat per la petició (text) i la petició (query) tal com l'ha interpretada el servidor d'APIs. Si la petició no especificava un dels formats previstos per alguna API, s'utilitzarà XML en la resposta.
Ex. 8: Contingut de la resposta XML a la petició en un format erroni
<?xml version="1.0" encoding="utf-8" ?>
<errors>
<error>
<id>105</id>
<text xml:lang="ca">
"sas" no és un format vàlid (xml, json, php) de l'operació cerca de la versió v1 del servei pob.
</text>
</error>
<query>https://api.idescat.cat/pob/v1/cerca.sas?q=abrera</query>
</errors>
Ex. 9: Contingut de la resposta JSON a la petició d'una operació inexistent
{
"error":[
{
"id":"104",
"text":"\"search\" no és una operació vàlida (cerca, sug) de la versió v1 del servei pob."
}
],
"query":"https:\/\/api.idescat.cat\/pob\/v1\/search.json?q=abrera"
}
Ex. 10: Contingut de la resposta en format PHP serialitzat a una petició sense versió
a:2:{
s:5:"error";
a:1:{
i:0;
a:2:{
s:2:"id";
s:3:"002";
s:4:"text";
s:79:"Per al servei indicadors cal especificar una versió (v1).";
}
}
s:5:"query";
s:56:"https:\/\/api.idescat.cat\/indicadors\/dades.php";
}
Ex. 11: Contingut de la resposta en format text a una petició que no suporta aquest format per al servei/versió/operació especificats
***ERROR*** 105 "txt" no és un format vàlid (xml, json, php) de l'operació cerca de la versió v1 del servei pob. https://api.idescat.cat/pob/v1/cerca.txt?q=abrera
Els codis d'error indiquen si no s'ha especificat en la petició una informació requerida o si s'ha fet amb un valor incorrecte (i la informació no preveu un valor per defecte):
| Falta | Valor incorrecte | |
|---|---|---|
| Servei | 001 | 101 |
| Versió | 002 | 102 |
| Subservei | 003 | 103 |
| Operació | 004 | 104 |
| Format | 005 | 105 |
| Paràmetre | 006 | 106 |
2.2. Formats suportats
En l'actualitat, els formats de resposta suportats amb caràcter general són XML, JSON i PHP serialitzat. Per a més informació, consulteu la secció 1.1.3. Format.