Interfaz de programación de aplicaciones (API)
El Idescat expone parte de sus datos a través de una colección de API de tipo REST (RESTful Web Services). Las API del Idescat ofrecen métodos para que los programas de terceros puedan obtener información del Instituto de Estadística de Cataluña e integrarla en otros servicios. La utilización de cualquiera de las API del Idescat conlleva la aceptación de las condiciones de uso del servicio.
| URI base | https://api.idescat.cat/{servicio}/v{versión principal}/{operación}.{formato}[?parámetros] |
|---|---|
| Método HTTP | GET |
| Formatos de la respuesta | xml, json, php |
| Versión | 1.00 (14/12/2009) |
| Atajos | Petición, Respuesta |
API disponibles
Condiciones de uso
- Debe reconocer el origen de los datos, ya sea utilizando los enlaces que proporcionen las API, ya sea enlazando con Idescat.cat.
- No está autorizado a mostrar el contenido proporcionado por las API de forma que no permita acceder a los enlaces con las páginas del Idescat. Tampoco está autorizado a incluir en un marco (<frame>, <iframe>) ninguna página web del Idescat.
- Al presentarlos, no está autorizado a modificar o editar los datos, metadatos o enlaces proporcionados por las API.
- Debe asegurar que el sentido del contenido proporcionado por las API no se cambia o distorsiona.
- El uso de las API del Idescat no supone ningún tipo de apoyo, relación o afiliación entre el sitio web que las utiliza y el Instituto de Estadística de Cataluña. No está autorizado a mostrar la información proporcionada por las API del Idescat, de tal forma que se sugiera este apoyo, relación o afiliación.
- El Idescat se reserva el derecho de limitar las peticiones repetidas desde un mismo origen para garantizar el acceso al servicio para todo el mundo. Es responsabilidad del cliente emplear los mecanismos necesarios para evitar peticiones de la misma información en espacios de tiempo breve. El uso excesivo puede ocasionar la finalización del servicio. Si piensa hacer un uso intensivo de las API del Idescat póngase en contacto con el Idescat a fin de poder garantizar que este uso no perjudicará la disponibilidad general del servicio.
- La cesión, utilización o explotación de las API deberán cumplir las estipulaciones contenidas en la legislación vigente y siempre se vincularán a usos legítimos.
- En caso de vulnerar estas condiciones, el Idescat se reserva el derecho de desactivar su acceso a las API. Asimismo, también será responsable de los daños que pueda suponer la explotación indebida de esta información.
- El Idescat se reserva el derecho de modificar discrecionalmente estas condiciones en cualquier momento, así como de finalizar esta relación y cancelar su uso, y declina cualquier garantía expresa o implícita relacionada con este servicio.
1. Petición
1.1. Anatomía de las peticiones
Toda petición debe especificar obligatoriamente un servicio, la versión principal del servicio, una operación válida por este servicio y un formato de respuesta. Opcionalmente, se pueden especificar una serie de parámetros generales y específicos del servicio.
https://api.idescat.cat/{servicio}
Algunos servicios pueden compartir la sintaxis de las peticiones y la estructura de las respuestas. Estos son tratados como un único servicio que dispone de subservicios. En este caso, la forma de la petición es:
https://api.idescat.cat/{servicio}
A pesar de que esta es la forma en la que internamente son tratadas todas las peticiones, las API también suelen admitir una sintaxis externa más amigable que no requiere especificar una operación (ver Invocación sin operación).
1.1.1. Servicio y versión
Cada servicio dispone de un identificador, de una versión y de unos parámetros específicos. Por ejemplo, el servicio de Indicadores al día se identifica con el valor indicadors y sólo dispone de una versión (1).
Ej. 1: Petición a la versión 1 del servicio de Indicadores al día
https://api.idescat.cat/indicadors/v1 /{…}
Los servicios pueden tener diferentes versiones principales, incompatibles entre sí. Las mejoras incrementales no afectan a la versión principal (por ejemplo, 1.01 respecto a 1.00) y, por lo tanto, tampoco a la petición.
1.1.2. Operación
Los servicios suelen soportar una diversidad de operaciones. Por ejemplo, el servicio indicadors admite la operación dades, que retorna resultados estadísticos, pero también la operación nodes.
Ej. 2: Dos peticiones al mismo servicio pero a operaciones diferentes
https://api.idescat.cat/indicadors/v1 /dades.{…}
https://api.idescat.cat/indicadors/v1 /nodes.{…}
El servicio y la operación determinan la estructura del documento retornado.
1.1.3. Formato
Determina el formato de la salida. Admite tres valores con carácter general:
- xml: retorna el resultado en formato eXtensible Markup Language.
- json: retorna el resultado en formato JavaScript Object Notation. Permite especificar una función de devolución con el parámetro callback con el nombre de la función. Aunque JSON es una cadena codificada en UTF-8, por conveniencia, la salida en este formato tienen en cuenta el valor especificado en enc.
- php: retorna el resultado en formato PHP serializado. Esta salida tiene la misma estructura que la salida en formato JSON: se trata de una cadena que puede ser deserializada para crear un objeto PHP (no una matriz). En este caso, el resultado siempre se retorna codificado en UTF-8 con independencia del valor de enc.
Ej. 3: Varias peticiones con respuesta en diferentes formatos
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ámetros generales
Toda petición tiene unos parámetros generales (comunes a todos los servicios) y unos parámetros específicos del servicio, documentados en la API del servicio.
1.2.1. Idioma de la respuesta (lang)
Admite tres valores:
- ca: catalán (valor por defecto)
- es: castellano
- en: inglés
Ej. 4: Resultado en castellano
https://api.idescat.cat/indicadors/v1 /dades.xml ?lang=es
1.2.2. Codificación de la respuesta (enc)
Este parámetro admite dos valores: utf-8 (valor por defecto) e iso-8859-1.
Ej. 5: Resultado codificado en ISO-8859-1
https://api.idescat.cat/indicadors/v1 /dades.xml ?enc=iso-8859-1
Si el formato de la respuesta es php la codificación es UTF-8, sea cual sea el valor de enc.
1.3. Parámetros específicos
Además de los parámetros generales descritos en el apartado anterior, cada servicio admite unos parámetros específicos ("variables") que permiten configurar la información obtenida. Estos parámetros están documentados en la API del servicio.
Por ejemplo, la operación dades del servicio indicadors permite seleccionar el número de indicadores obtenidos gracias a los parámetros tt, max y min.
Ej. 6: Parámetros específicos
https://api.idescat.cat/indicadors/v1 /dades.xml ?tt=10 &max=10 &min=3
1.3.1. El parámetro general p
Las variables del servicio (o "parámetros específicos") pueden encapsularse en un parámetro general para efectuar una llamada más compacta. Para hacerlo hay que incluir una serie de parejas variable/valor separadas por puntos y coma.
Ej. 7: Peticiones sinónimas
https://api.idescat.cat/indicadors/v1 /dades.xml ?tt=10 &max=10 &min=3
https://api.idescat.cat/indicadors/v1 /dades.json ?p=tt/10;max/10;min/3
1.4. Invocación sin operación
Por razones de amigabilidad, algunas API pueden admitir peticiones con una sintaxis que no requiere especificar una de las operaciones generales previstas. En su lugar, se utilizan referencias a recursos que suelen ser específicos de cada API. Consulte la documentación de cada API para saber si la invocación sin operación está disponible y para conocer su sintaxis específica.
Como internamente las API utilizan siempre la invocación con operación, los mensajes de error incluyen las peticiones en esta forma, con independencia de cómo fueron especificadas por el usuario.
2. Respuesta
2.1. Códigos de respuesta y errores
En caso de que el servidor no pueda atender la petición, el código retornado será 500 (Server Error) o 503 (Service Unavailable). En el resto de casos, podemos distinguir dos tipos de petición que retornan diferentes códigos de respuesta HTTP:
- Correcta: retorna el código de respuesta 200 (OK).
- Incorrecta: retorna el código de respuesta 400 (Bad Request). Como algunos clientes interceptan el contenido de la respuesta cuando el código es de error, por conveniencia se puede forzar el código 200 (OK) añadiendo a la petición el parámetro rc con valor 200 (este parámetro se ignorará si se especifica otro valor).
En el caso de petición incorrecta, el documento retornado contendrá el código de error (id), un texto explicativo en el idioma solicitado por la petición (text) y la petición (query) tal como lo ha interpretado el servidor de API. Si la petición no especificaba uno de los formatos previstos por alguna API, se utilizará XML en la respuesta.
Ej. 8: Contenido de la respuesta XML a la petición en un formato erróneo
<?xml version="1.0" encoding="utf-8" ?>
<errors>
<error>
<id>105</id>
<text xml:lang="es">
"sas" no es un formato válido (xml, json, php) de la operación cerca de la versión v1 del servicio pob.
</text>
</error>
<query>https://api.idescat.cat/pob/v1/cerca.sas?q=abrera&lang=es</query>
</errors>
Ej. 9: Contenido de la respuesta JSON a la petición de una operación inexistente
{
"error":[
{
"id":"104",
"text":"\"search\" no es una operación válida (cerca, sug) de la versión v1 del servicio pob."
}
],
"query":"https:\/\/api.idescat.cat\/pob\/v1\/search.json?q=abrera&lang=es"
}
Ej. 10: Contenido de la respuesta en formato PHP serializado a una petición sin versión
a:2:{
s:5:"error";
a:1:{
i:0;
a:2:{
s:2:"id";
s:3:"002";
s:4:"text";
s:79:"Para el servicio indicadors hay que especificar una versión (v1).";
}
}
s:5:"query";
s:56:"https:\/\/api.idescat.cat\/indicadors\/dades.php?lang=es";
}
Ej. 11: Contenido de la respuesta en formato texto a una petición que no soporta este formato para el servicio/versión/operación especificados
***ERROR*** 105 "txt" no es un formato válido (xml, json, php) de la operación cerca de la versión v1 del servicio pob. https://api.idescat.cat/pob/v1/cerca.txt?q=abrera&lang=es
Los códigos de error indican si no se ha especificado en la petición una información requerida o si se ha efectuado con un valor incorrecto (y la información no prevé un valor por defecto):
| Falta | Valor incorrecto | |
|---|---|---|
| Servicio | 001 | 101 |
| Versión | 002 | 102 |
| Subservicio | 003 | 103 |
| Operación | 004 | 104 |
| Formato | 005 | 105 |
| Parámetro | 006 | 106 |
2.2. Formatos soportados
En la actualidad, los formatos de salida soportados con carácter general son XML, JSON y PHP serializado. Para más información, consulte la sección 1.1.3. Formato.