Indicadores al día. API

1.1 Anatomía de las peticiones

Toda petición debe especificar obligatoriamente el servicio, la versión, la operación y el formato. Versión y operación son características específicas de cada servicio. Si no se dice lo contrario, el servicio soporta los formatos de respuesta generales de las API del Idescat. Para más información, consulte el apartado Anatomía de las peticiones en la documentación general de las API del Idescat.

1.1.1 Identificador del servicio y versión

El servicio de Indicadores al día se identifica con el valor indicadors.

https://api.idescat.cat/indicadors/v1/{…}

1.1.2 Operaciones

Admite dos tipos de operaciones:

• dades: Devuelve datos en forma de serie temporal en Cataluña y España del indicador al día escogido. Véase la sección 1.2.1.

  https://api.idescat.cat/indicadors/v1/dades.{…}

• nodes: Devuelve el árbol de los indicadores disponibles. Véase la sección 1.2.2.

  https://api.idescat.cat/indicadors/v1/nodes.{…}

1.2 Parámetros específicos

Los parámetros específicos ("variables") permiten escoger la información que devolverá una determinada operación del servicio de Indicadores al día. Se pueden especificar como parámetros individuales o en un único parámetro p (forma compacta). En esta documentación, se utiliza siempre la forma compacta.

Para conocer los parámetros generales disponibles para cualquier servicio, consulte la documentación de las API del Idescat.

1.2.1 Operación dades

Permite seleccionar un conjunto fijo de indicadores del cual se quiere obtener información o bien aquellos indicadores más recientes (sean los que sean).

1.2.1.1 Indicadores predeterminados

• i: lista de los identificadores (separados por comas) de cuyos indicadores se devolverá información.

Para conocer los identificadores de los diferentes indicadores disponibles, utilice la operación nodes. El ejemplo 23 muestra la lista actual de indicadores y sus identificadores.

Si esta variable de selección está presente (aunque no tenga un valor asignado), se ignorará el resto de parámetros específicos.

Ej. 1: Series de Cataluña y España de los indicadores 0801 y 0802, en formato XML

https://api.idescat.cat/indicadors/v1/dades.xml?p=i/0801,0802

1.2.1.2 Últimos indicadores

Permite seleccionar los indicadores según la combinación de tres criterios:

• tt: tiempo transcurrido. Permite seleccionar los indicadores de acuerdo con los días transcurridos desde su publicación. El valor 1 selecciona los indicadores publicados hoy; 2 selecciona los indicadores de hoy y ayer; etc. El valor por defecto es 0 e indica que la selección de indicadores no está limitada por el tiempo transcurrido.
• max: máximo número de indicadores. Limita el número de indicadores mostrados, sea cual sea el tiempo transcurrido. El valor 0 indica que la selección de indicadores no está limitada por un número. El valor por defecto es 6.
• min: mínimo número de indicadores. Garantiza que se muestre un número mínimo de indicadores, sea cual sea el tiempo transcurrido. El valor por defecto es 6.

Los indicadores se devuelven en orden inversamente cronológico.

Ej. 2: Indicadores de los últimos 14 días (incluido hoy), pero garantizando la obtención de 3 indicadores y limitando el resultado a un máximo de 10, en formato XML

https://api.idescat.cat/indicadors/v1/dades.xml?p=tt/14;max/10;min/3

Ej. 3: Últimos 3 indicadores, en formato JSON

https://api.idescat.cat/indicadors/v1/dades.json?p=tt/0;max/3;min/3

Ej. 4: Indicadores de los últimos 3 días (incluido hoy) sin importar el número máximo ni el mínimo, en formato PHP serializado

https://api.idescat.cat/indicadors/v1/dades.php?p=tt/3;max/0;min/0

Ej. 5: Todos los indicadores existentes sin importar el tiempo transcurrido, en formato XML

https://api.idescat.cat/indicadors/v1/dades.xml?p=tt/0;max/0;min/0

Atención: El tiempo de respuesta de esta petición puede ser significativo. Se aconseja dimensionar las peticiones a las necesidades reales de información. En ningún caso se deben solicitar todos los indicadores sin mantener algún tipo de caché en la máquina solicitante.

1.2.2 Operación nodes

Devuelve la lista de indicadores disponibles, con su identificador y una descripción, agrupados en apartados y subapartados. El parámetro i permite filtrar los apartados que se muestran.

• i: lista de los identificadores (separados por comas) de cuyos apartados se devolverá información. Si no se especifica, se mostrarán todos los apartados.

Para conocer los identificadores de los apartados disponibles actualmente, utilice la operación nodes sin especificar i.

Ej. 6: Árbol de todos los indicadores disponibles, en formato JSON con función de devolución ("func")

https://api.idescat.cat/indicadors/v1/nodes.json?callback=func

Ej. 7: Árbol de los Indicadores básicos de Cataluña (2), en formato XML

https://api.idescat.cat/indicadors/v1/nodes.xml?p=i/2

Para conocer los códigos de respuesta HTTP devueltos y los formatos soportados por cualquier servicio, consulte el apartado 2 de las API del Idescat.

2.1 Estructura de los resultados

2.1.1 El elemento raíz indicadors

El elemento raíz (indicadors) incluye los siguientes atributos:

• version: versión del servicio.
• lang: idioma general del documento. Si el valor de algún elemento textual no utiliza este idioma tendrá su propio atributo lang. Los valores aceptados en la actualidad son ca (valor por defecto), es y en.
• o: operación solicitada.
• p: valores asignados a los parámetros específicos, si hay.
• n: número de indicadores o nodos finales con información de que se han incluido en el documento. Este número no coincide con el número de elementos devueltos cuando de algún indicador o nodo final no se ha obtenido información válida.

Ej. 8: Atributos del elemento raíz en una operación dades

<indicadors
 xmlns:dc="http://purl.org/dc/elements/1.1/"
 version="1.00"
 lang="ca"
 o="dades"
 n="6"
 p="tt=0;max=6;min=6;"
>

Ej. 9: Atributos del elemento raíz en una operación nodes

<indicadors
 version="1.00"
 lang="ca"
 o="nodes"
 n="54"
 p="i=2"
>

2.1.2 Los elementos i de la operación dades

La información de cada indicador se incluye en el elemento i. Además de la información de Cataluña, podría incluir información de comparación de uno o más ámbitos geográficos (en la actualidad, sólo de España).

Ej. 10: Elemento i de la operación dades

<i id="0302">
 <c>Pernoct. hotels</c>

 <r title="gen/09">2009-01</r>
 <d>Variació interanual de pernoctacions en establiments hotelers</d>
 <v>-12.0</v>
 <s>Idescat, a partir de l'Enquesta d'ocupació hotelera de l'INE</s>

 <vc g="es">-11.5</vc>
 <sc g="es">INE</sc>
 <ts>-1.0,7.9,15.2,-16.6,2.4,-1.2,2.8,1.4,-3.7,-5.6,-10.5,-6.6,-12.0</ts>
 <tsc g="es">1.2,8.6,9.6,-11.9,6.2,-2.8,0.4,-0.5,-3.2,-5.3,-11.0,-10.6,-11.5</tsc>

 <u s="%">%</u>
 <l>https://www.idescat.cat/economia/inec?tc=3&id=0302</l>
 <m>https://www.idescat.cat/economia/inec?tc=7&id=0302</m>

 <t i="c">Conjuntura econòmica</t>
 <dc:date>2009-03-04T14:07:00+00:00</dc:date>
</i>

2.1.2.1 Elementos generales

Los elementos generales son:

• c: concepto. Por ejemplo, "IPC".
• d: descripción del indicador. Por ejemplo, "Variación interanual del índice de precios de consumo".
• r: referencia temporal. Contiene al menos un año (cuatro dígitos). Por ejemplo, "2009". La especificación de año puede ir seguida de un guión. Si tras el guión hay un número de dos dígitos indica mes ("2009-10": octubre del 2009); si sólo hay uno, indica trimestre ("2009-3": tercer trimestre del 2009). Otros periodos de referencia se expresan en forma de intervalo (fecha de inicio y final separadas por coma). Por ejemplo, "2009-01,2009-05" indica el periodo enero-mayo del 2009. El elemento r contiene un atributo title que incluye la referencia temporal en forma de texto breve en el idioma general lang. Por ejemplo: "gen/09".
• u: este elemento se utiliza para facilitar información sobre las unidades del indicador. Su contenido puede proporcionar un texto brevísimo concatenable al valor. En la actualidad, sólo se utiliza para pasar el símbolo "%"; en el resto de casos está en blanco. Este elemento contiene un atributo s que no está plenamente desarrollado en la actual versión de la API.
• l: Enlace con la página del indicador.
• m: Enlace con la página de la metodología del indicador (a partir del 24 de abril de 2018, los indicadores dejaron de tener una página específica sobre su metodología y, como consecuencia, este elemento dejó de proporcionarse).
• t: Texto descriptivo del tipo de indicador en el idioma general lang. El atributo i incluye una versión codificada.
• dc:date: fecha de actualización del indicador (por ejemplo, "2009-03-08T11:05:00+00:00"). Véase la Dublin Core Metadata Initiative.

2.1.2.2 Elementos específicos del ámbito geográfico

Indicadores al día está concebido como un servicio que proporciona información de Cataluña. Adicionalmente, puede ofrecer la misma información para otros ámbitos de comparación. La información de Cataluña está contenida en los siguientes elementos (que siempre están presentes):

• Valores

  Los elementos que contienen valores indican los decimales con punto (por ejemplo, "10.5"). Los valores faltantes se indican con "_".

  • v: valor del último periodo disponible. Este valor, que también se proporciona en el elemento ts, se ofrece en v por conveniencia.
  • ts: serie temporal. Los valores de la serie, ordenados de más antiguo a más reciente, van separados por comas. En general, la serie se inicia en el mismo periodo de referencia de los datos actuales pero de un año atrás. Por lo tanto, si la periodicidad de los datos es mensual, se incluyen 13 observaciones y, si es trimestral, 5. En el caso de valores anuales, se ofrecen hasta 5 años (o menos si la serie de datos disponibles es más corta). Si no hay una serie temporal disponible, este elemento no estará presente.
• Textos
  • s: texto que expresa la fuente de los datos.

Si hay información disponible para otros ámbitos geográficos, se incluyen en los elementos vc, tsc y sc, que tienen el mismo significado que los correspondientes v, ts y s. Estos tres nuevos elementos incluyen un atributo g que indica el ámbito geográfico (en estos momentos siempre es igual a "es"). Si el último valor de la serie del ámbito de comparación (tsc) no está disponible, vc estará presente pero con el valor "_".

Dado que en estos momentos la fuente de los datos (tanto para Cataluña como para España) no está traducida, cuando se solicite el resultado en un idioma diferente del catalán tanto s como sc incluirán el atributo lang igual a "ca".

2.1.3 Los elementos v de la operación nodes

Los indicadores se agrupan en apartados y subapartados. Esta jerarquía se expresa en una serie de elementos v imbricados. Cada elemento dispone de un identificador (atributo id). Los nodos finales (indicadores) contienen un texto descriptivo sobre la forma de cómputo (atributo desc), así como la fecha de actualización del indicador (atributo date).

Ej. 11: Elementos v de la operación nodes

<v id="0">Indicadors de conjuntura
 <v id="00">Comptabilitat trimestral
  <v id="0005"
       desc="Variació interanual en volum corregida d'efectes estacionals i de calendari"
       date="2009-11-20T14:36:00+00:00">
       PIB</v>
 </v>
 <v id="01">Indústria
  <v id="0101"
       desc="Variació interanual de l'índex de producció industrial"
       date="2009-10-14T08:32:00+00:00">
       IPI
  </v>
  <v id="0102"
       desc="Saldo de respostes sobre el clima industrial"
       date="2009-11-06T10:53:00+00:00">
       Clima industrial
  </v>
  <v id="0103"
       desc="Variació interanual de la facturació d'energia elèctrica"
       date="2009-11-10T12:08:00+00:00">
       Energia elèctrica
  </v>
 </v>
...
</v>

2.2 Errores

Las API del Idescat utilizan códigos de respuesta normalizados para indicar si la petición ha tenido éxito o si ha fracasado. Las peticiones al API de Indicadores al día pueden tener éxito, pero no devolver alguno de los indicadores solicitados, bien porque no existe en la actualidad o no ha existido nunca (identificador incorrecto), bien porque el indicador no esté disponible temporalmente (por ejemplo, porque se está revisando).

2.2.1 Operación dades

El elemento i del indicador sin información dispondrá del atributo error para indicar:

• 403: Indicador existente pero no disponible temporalmente. El elemento c será el único descendente devuelto.
• 404: Indicador inexistente en la actualidad (identificador no válido). El elemento c contendrá un texto explicativo del error en el idioma de la petición.

Se puede saber el número de indicadores de los cuales se ha devuelto información gracias al atributo n del elemento indicadors.

Ej. 12: Salida con dos indicadores erróneos de los tres solicitados

<?xml version="1.0" encoding="utf-8" ?>
<indicadors
 xmlns:dc="http://purl.org/dc/elements/1.1/"
 lang="ca"
 o="dades"
 n="1"
 p="i=0501,9999,0701"
>
 <i id="0501" error="403">
   <c>Vehicles</c>
 </i>
 <i id="9999" error="404">
   <c>Indicador no trobat</c>
 </i>
 <i id="0701">
     <c>IPC</c>
     <r title="set/09">2009-09</r>
     <d>Variació interanual de l'índex de preus de consum</d>
     <v>-0.5</v>
     <s>INE</s>
     <vc g="es">-1.0</vc>
     <sc g="es">INE</sc>
     <ts>4.5,3.6,2.5,1.6,1.1,1.0,0.4,0.4,-0.3,-0.5,-0.9,-0.3,-0.5</ts>
     <tsc g="es">4.5,3.6,2.4,1.4,0.8,0.7,-0.1,-0.2,-0.9,-1.0,-1.4,-0.8,-1.0</tsc>
     <u s="%">%</u>
     <l>https://www.idescat.cat/economia/inec?tc=3&id=0701</l>
     <m>https://www.idescat.cat/economia/inec?tc=7&id=0701</m>
     <t i="c">Conjuntura econòmica</t>
     <dc:date>2009-10-14T08:32:00+00:00</dc:date>
  </i>
</indicadors>

2.2.2 Operación nodes

El elemento v de aquellos indicadores existentes pero no disponibles temporalmente tendrá el atributo error con valor 403. Además, no dispondrá de atributo desc ni date.

Ej. 13: Fragmento del árbol con un indicador no disponible temporalmente

<v id="59">Sector exterior
 <v id="5901" error="403">Exportacions</v>
 <v id="5905" desc="Variació de les importacions" date="2009-10-24T17:32:00+00:00">Importacions</v>
</v>