Saltar al contingut principal

Indicadors al dia. API RSS

El servei d'Indicadors al dia proporciona informació bàsica d'una selecció d'indicadors de Catalunya.

La utilització d'aquest servei comporta l'acceptació de les condicions d'ús de les APIs de l'Idescat.

Resum
URI base https://api.idescat.cat/indicadors/v1/{operació}.{format}[?paràmetres]
Mètode HTTP GET
Formats de la resposta xml, json, php
Versió 1.00 (14/12/2009)
Dreceres Petició, Resposta, Exemples
Operacions dades, nodes

1. Petició

1.1 Anatomia de les peticions

Tota petició ha d'especificar obligatòriament el servei, la versió, l'operació i el format. Versió i operació són característiques específiques de cada servei. Si no es diu el contrari, el servei suporta els formats de resposta generals de les APIs de l'Idescat. Per a més informació, consulteu l'apartat Anatomia de les peticions a la documentació general de les APIs de l'Idescat.

1.1.1 Identificador del servei i versió

El servei d'Indicadors al dia s'identifica amb el valor indicadors.

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

1.1.2 Operacions

Admet dos tipus d'operacions:

  • dades: Retorna dades en forma de sèrie temporal per a Catalunya i Espanya de l'indicador al dia escollit. Vegeu la secció 1.2.1. 
    https://api.idescat.cat/indicadors/v1/dades.{…}
  • nodes: Retorna l'arbre dels indicadors disponibles. Vegeu la secció 1.2.2. 
    https://api.idescat.cat/indicadors/v1/nodes.{…}

1.2 Paràmetres específics

Els paràmetres específics ("variables") permeten escollir la informació que retornarà una determinada operació del servei d'Indicadors al dia. Es poden especificar com a paràmetres individuals o en un únic paràmetre p (forma compacta). En aquesta documentació, s'utilitza sempre la forma compacta.

Per conèixer els paràmetres generals disponibles per a qualsevol servei, consulteu la documentació de les APIs de l'Idescat.

1.2.1 Operació dades

Permet seleccionar un conjunt fix d'indicadors del qual es vol obtenir informació o bé aquells indicadors més recents (siguin els que siguin).

1.2.1.1 Indicadors predeterminats
  • i: llista dels identificadors (separats per comes) dels indicadors dels quals es retornarà informació.

Per conèixer els identificadors dels diferents indicadors disponibles, utilitzeu l'operació nodes. L'exemple 23 mostra la llista actual d'indicadors i els seus identificadors.

Si aquesta variable de selecció està present (encara que no tingui un valor assignat), s'ignoraran la resta de paràmetres específics.

Ex. 1: Sèries per a Catalunya i Espanya dels indicadors 0801 i 0802, en format XML
https://api.idescat.cat/indicadors/v1/dades.xml?p=i/0801,0802
1.2.1.2 Darrers indicadors

Permet seleccionar els indicadors d'acord amb la combinació de tres criteris:

  • tt: temps transcorregut. Permet seleccionar els indicadors d'acord amb els dies transcorreguts des de la seva publicació. El valor 1 selecciona els indicadors publicats avui; 2 selecciona els indicadors d'avui i ahir; etc. El valor per defecte és 0 i indica que la selecció d'indicadors no està limitada pel temps transcorregut.
  • max: màxim nombre d'indicadors. Limita el nombre d'indicadors mostrats, sigui quin sigui el temps transcorregut. El valor 0 indica que la selecció d'indicadors no està limitada per un nombre. El valor per defecte és 6.
  • min: mínim nombre d'indicadors. Garanteix que es mostri un nombre mínim d'indicadors, sigui quin sigui el temps transcorregut. El valor per defecte és 6.

Els indicadors es retornen en ordre inversament cronològic.

Ex. 2: Indicadors dels darrers 14 dies (inclòs avui), però garantint l'obtenció de 3 indicadors i limitant el resultat a un màxim de 10, en format XML
https://api.idescat.cat/indicadors/v1/dades.xml?p=tt/14;max/10;min/3
Ex. 3: Darrers 3 indicadors, en format JSON
https://api.idescat.cat/indicadors/v1/dades.json?p=tt/0;max/3;min/3
Ex. 4: Indicadors dels darrers 3 dies (inclòs avui) sense importar el nombre màxim ni el mínim, en format PHP serialitzat
https://api.idescat.cat/indicadors/v1/dades.php?p=tt/3;max/0;min/0
Ex. 5: Tots els indicadors existents sense importar el temps transcorregut, en format XML
https://api.idescat.cat/indicadors/v1/dades.xml?p=tt/0;max/0;min/0

Atenció: El temps de resposta d'aquesta petició pot ser significatiu. S'aconsella dimensionar les peticions a les necessitats reals d'informació. En cap cas s'han de sol·licitar tots els indicadors sense mantenir algun tipus de caché en la màquina sol·licitant.

1.2.2 Operació nodes

Retorna la llista d'indicadors disponibles, amb el seu identificador i una descripció, agrupats en apartats i subapartats. El paràmetre i permet filtrar els apartats que es mostren.

  • i: llista dels identificadors (separats per comes) dels apartats dels quals es retornarà informació. Si no s'especifica, es mostraran tots els apartats.

Per conèixer els identificadors dels apartats disponibles actualment, utilitzeu l'operació nodes sense especificar i.

Ex. 6: Arbre de tots els indicadors disponibles, en format JSON amb funció de devolució ("func")
https://api.idescat.cat/indicadors/v1/nodes.json?callback=func
Ex. 7: Arbre dels Indicadors bàsics de Catalunya (2), en format XML
https://api.idescat.cat/indicadors/v1/nodes.xml?p=i/2

2. Resposta

Per conèixer els codis de resposta HTTP retornats i els formats suportats per qualsevol servei, consulteu l'apartat 2 de les APIs de l'Idescat.

2.1 Estructura dels resultats

2.1.1 L'element arrel indicadors

L'element arrel (indicadors) inclou els següents atributs:

  • version: versió del servei.
  • lang: idioma general del document. Si el valor d'algun element textual no utilitza aquest idioma tindrà el seu propi atribut lang. Els valors acceptats en l'actualitat són ca (valor per defecte), es i en.
  • o: operació sol·licitada.
  • p: valors assignats als paràmetres específics, si n'hi ha.
  • n: nombre d'indicadors o nodes finals amb informació que s'han inclòs en el document. Aquest nombre no coincideix amb el nombre d'elements retornats quan d'algun indicador o node final no s'ha obtingut informació vàlida.
Ex. 8: Atributs de l'element arrel en una operació 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;"
>
Ex. 9: Atributs de l'element arrel en una operació nodes
<indicadors
 version="1.00"
 lang="ca"
 o="nodes"
 n="54"
 p="i=2"
>

2.1.2 Els elements i de l'operació dades

La informació de cada indicador s'inclou a l'element i. A més de la informació de Catalunya, podria incloure informació de comparació d'un o més àmbits geogràfics (en l'actualitat, només d'Espanya).

Ex. 10: Element i de l'operació 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 Elements generals

Els elements generals són:

  • c: concepte. Per exemple, "IPC".
  • d: descripció de l'indicador. Per exemple, "Variació interanual de l'índex de preus de consum".
  • r: referència temporal. Conté almenys un any (quatre dígits). Per exemple, "2009". L'especificació d'any pot anar seguida d'un guió. Si després del guió hi ha un nombre de dos dígits indica mes ("2009-10": octubre del 2009); si només n'hi ha un, indica trimestre ("2009-3": tercer trimestre del 2009). Altres períodes de referència s'expressen en forma d'interval (data d'inici i final separades per coma). Per exemple, "2009-01,2009-05" indica el període gener-maig del 2009. L'element r conté un atribut title que inclou la referència temporal en forma de text breu en l'idioma general lang. Per exemple: "gen/09".
  • u: aquest element s'utilitza per facilitar informació sobre les unitats de l'indicador. El seu contingut pot proporcionar un text brevíssim concatenable al valor. En l'actualitat, només s'utilitza per passar el símbol "%"; en la resta de casos està en blanc. Aquest element conté un atribut s que no està plenament desenvolupat en l'actual versió de l'API.
  • l: Enllaç amb la pàgina de l'indicador.
  • m: Enllaç amb la pàgina de la metodologia de l'indicador (a partir del 24 d'abril de 2018, els indicadors van deixar de tenir una pàgina específica sobre la seva metodologia i, com a conseqüència, aquest element va deixar de proporcionar-se).
  • t: Text descriptiu del tipus d'indicador en l'idioma general lang. L'atribut i inclou una versió codificada.
  • dc:date: data d'actualització de l'indicador (per exemple, "2009-03-08T11:05:00+00:00"). Vegeu la Dublin Core Metadata Initiative.
2.1.2.2 Elements específics de l'àmbit geogràfic

Indicadors al dia està concebut com un servei que proporciona informació de Catalunya. Addicionalment, pot oferir la mateixa informació per a d'altres àmbits de comparació. La informació de Catalunya està continguda en els següents elements (que sempre estan presents):

  • Valors

    Els elements que contenen valors indiquen els decimals amb punt (per exemple, "10.5"). Els valors faltants s'indiquen amb "_".

    • v: valor del darrer període disponible. Aquest valor, que també es proporciona a l'element ts, s'ofereix a v per conveniència.
    • ts: sèrie temporal. Els valors de la sèrie, ordenats de més antic a més recent, van separats per comes. En general, la sèrie s'inicia en el mateix període de referència de les dades actuals però d'un any enrere. Per tant, si la periodicitat de les dades és mensual, s'inclouen 13 observacions i, si és trimestral, 5. En el cas de valors anuals, s'ofereixen fins a 5 anys (o menys si la sèrie de dades disponibles és més curta). Si no hi ha una sèrie temporal disponible, aquest element no estarà present.
  • Textos
    • s: text que expressa la font de les dades.

Si hi ha informació disponible per a d'altres àmbits geogràfics, s'inclouen en els elements vc, tsc i sc, que tenen el mateix significat que els corresponents v, ts i s. Aquests tres nous elements inclouen un atribut g que indica l'àmbit geogràfic (en aquests moments sempre és igual a "es"). Si el darrer valor de la sèrie de l'àmbit de comparació (tsc) no està disponible, vc estarà present però amb el valor "_".

Com que en aquests moments la font de les dades (tant per a Catalunya com per a Espanya) no està traduïda, quan se sol·liciti el resultat en un idioma diferent del català tant s com sc inclouran l'atribut lang igual a "ca".

2.1.3 Els elements v de l'operació nodes

Els indicadors s'agrupen en apartats i subapartats. Aquesta jerarquia s'expressa en un seguit d'elements v imbricats. Cada element disposa d'un identificador (atribut id). Els nodes finals (indicadors) contenen un text descriptiu sobre la forma de còmput (atribut desc), així com la data d'actualització de l'indicador (atribut date).

Ex. 11: Elements v de l'operació 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 Errors

Les APIs de l'Idescat utilitzen codis de resposta normalitzats per indicar si la petició ha tingut èxit o si ha fracassat. Les peticions a l'API d'Indicadors al dia poden tenir èxit, però no retornar algun dels indicadors sol·licitats, bé perquè no existeix en l'actualitat o no ha existit mai (identificador incorrecte), bé perquè l'indicador no estigui disponible temporalment (per exemple, perquè s'està revisant).

2.2.1 Operació dades

L'element i de l'indicador sense informació disposarà de l'atribut error per indicar:

  • 403: Indicador existent però no disponible temporalment. L'element c serà l'únic descendent retornat.
  • 404: Indicador inexistent en l'actualitat (identificador no vàlid). L'element c contindrà un text explicatiu de l'error en l'idioma de la petició.

Es pot saber el nombre d'indicadors dels quals s'ha retornat informació vàlida gràcies a l'atribut n de l'element indicadors.

Ex. 12: Sortida amb dos indicadors erronis dels tres sol·licitats
<?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ó nodes

L'element v d'aquells indicadors existents però no disponibles temporalment tindrà l'atribut error amb valor 403. A més, no disposarà d'atribut desc ni date.

Ex. 13: Fragment de l'arbre amb un indicador no disponible temporalment
<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>