Saltar al contingut principal

Calendari de difusió de resultats. API RSS

Aquesta API dona accés a la informació del calendari de l'Idescat de difusió de resultats. Les dates de publicació de les estadístiques que ofereix aquesta API permeten minimitzar el nombre de peticions i fer un ús més efectiu de la resta d'APIs.

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/cal/v1/{operació}.{format}[?paràmetres]
Mètode HTTP GET
Formats de la resposta xml, json, php, txt, ical
Versió 1.00 (01/06/2012)
Dreceres Petició, Resposta
Operacions dades, nodes

1. Petició

1.1. Característiques bàsiques

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. Aquest 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.

Addicionalment, l'operació dades pot retornar el calendari en format iCalendar. Aquest és un estàndard que en aquesta API pot sol·licitar-se especificant com a format txt o ics. L'única diferència és que, en el primer cas i per una qüestió d'homogeneïtat, la capçalera de la resposta declararà el tipus del contingut com a text/plain i en el segon, d'acord amb l'estàndard, com a text/calendar (i la disposició del contingut serà attachment i es facilitarà un nom de fitxer).

1.1.1. Identificador del servei i versió

L'identificador d'aquest servei és cal.

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

1.1.2. Operacions

Aquest servei admet dos tipus d'operacions:

  • dades: Retorna els esdeveniments inclosos en el calendari de difusió.
    https://api.idescat.cat/cal/v1/dades.{…}
  • nodes: Retorna la relació d'estadístiques incloses en el calendari de difusió.
    https://api.idescat.cat/cal/v1/nodes.{…}

1.2. Paràmetres específics

Aquest servei suporta els paràmetres generals (idioma i codificació) de les APIs de l'Idescat.

Els paràmetres específics permeten escollir la informació que retornarà una determinada operació del servei. Es poden especificar com a paràmetres individuals o en un únic paràmetre p (forma compacta).

1.2.1. Operació dades

L'operació dades retorna els esdeveniments de difusió de resultats estadístics de l'Idescat amb dia confirmat.

1.2.1.1. Filtre t

Aquest paràmetre serveix per especificar el període temporal del qual es volen recuperar esdeveniments. Es recomana especificar sempre aquest paràmetre. Si no s'especifica, es retornaran esdeveniments del conjunt de l'any més recent per al qual es disposa de calendari de difusió.

És important advertir que aquest paràmetre selecciona els esdeveniments segons la data de publicació dels resultats, no segons el període a què es refereixen.

Cal tenir en compte que el primer any per al qual es disposa de calendari és el 2012.

Ex. 1: Calendari de difusió de l'any 2012 en format XML
https://api.idescat.cat/cal/v1/dades.xml?t=2012
Ex. 2: Calendari de difusió de l'octubre del 2012 en format JSON
https://api.idescat.cat/cal/v1/dades.json?t=201210
Ex. 3: Calendari de difusió del 23 d'octubre del 2012 en format ICS
https://api.idescat.cat/cal/v1/dades.ics?t=20121023

Aquest paràmetre permet també especificar intervals utilitzant el guió.

Ex. 4: Calendari de difusió de l'octubre i el novembre del 2012 en format PHP serialitzat
https://api.idescat.cat/cal/v1/dades.php?t=201210-201211
Ex. 5: Calendari de difusió de la setmana del 22 d'octubre en format text
https://api.idescat.cat/cal/v1/dades.txt?t=20121022-20121028
1.2.1.2. Filtre id

Es pot utilitzar el paràmetre id per sol·licitar el calendari d'una determinada estadística.

Ex. 6: Calendari de difusió de l'any 2012 de l'enquesta de població activa (EPA) en format JSON
https://api.idescat.cat/cal/v1/dades.json?t=2012&id=epa

Per obtenir la relació d'estadístiques disponibles en un determinat període podeu utilitzar l'operació nodes.

1.2.2. Operació nodes

L'operació nodes retorna la relació d'estadístiques que s'han publicat o es publicaran en un determinat període i permet conèixer els valors vàlids del paràmetre id de l'operació dades.

1.2.2.1. Filtre t

Aquest paràmetre serveix per especificar el període temporal del qual es vol recuperar la denominació i el codi de les estadístiques que es difonen. Es recomana especificar sempre aquest paràmetre. Si no s'especifica, es retornarà la relació d'estadístiques que tenen alguna difusió de resultats durant el conjunt de l'any més recent del qual es disposi de calendari.

Ex. 7: Llista d'estadístiques que tenen difusió de resultats durant l'any 2012 i els seus codis, en format XML
https://api.idescat.cat/cal/v1/nodes.xml?t=2012

Per conèixer la sintaxi i totes les possibilitats d'aquest paràmetre, consulteu l'apartat corresponent a l'operació dades.

Ex. 8: Llista d'estadístiques que tenen difusió de resultats entre el 23 d'octubre i el 23 de novembre del 2012 i els seus codis, en format JSON
https://api.idescat.cat/cal/v1/nodes.json?t=20121023-20121123
1.2.2.2. Filtre id

Es pot utilitzar el paràmetre id per validar si una determinada estadística serà actualitzada en un determinat període de temps. També es pot fer servir per obtenir la denominació d'una determinada estadística a partir del seu codi.

Ex. 9: Estadística que té el codi IPRI amb difusió de resultats durant l'any 2012, en format XML
https://api.idescat.cat/cal/v1/nodes.xml?t=2012&id=ipri

En el cas de l'operació nodes, el paràmetre id admet una llista de valors separats per una coma (aquesta opció no està disponible en la invocació sense operació).

Ex. 10: Estadístiques que tenen els codis IPRI i IPI amb difusió de resultats durant l'any 2012, en format XML
https://api.idescat.cat/cal/v1/nodes.xml?t=2012&id=ipri,ipi

1.3. Invocació sense operació

Per raons d'amigabilitat, aquesta API admet peticions amb una sintaxi que no requereix especificar operacions (vegeu, a la documentació general de les APIs de l'Idescat, l'apartat 1.4. Invocació sense operació).

  • Calendari de difusió de resultats de l'any 2012, en format XML
    https://api.idescat.cat/cal/v1/calendari/2012.xml
  • Calendari de difusió de resultats del desembre del 2012, en format JSON
    https://api.idescat.cat/cal/v1/calendari/201212.json
  • Calendari de difusió de resultats de l'any 2012 de l'índex de producció industrial (IPI), en format ICS
    https://api.idescat.cat/cal/v1/calendari/2012/ipi.ics
  • Estadístiques que es publiquen l'any 2012, en format XML
    https://api.idescat.cat/cal/v1/estadistiques/2012.xml
  • Estadístiques que es publiquen l'any 2012 amb codi IPROSS, en format JSON
    https://api.idescat.cat/cal/v1/estadistiques/2012/ipross.json

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. Operació dades

L'estructura de la resposta de l'operació dades es basa en l'estàndard de text iCalendar. En el cas del format XML, s'utilitza el mapeig estàndard d'iCalendar anomenat xCal.

Ex. 11: Actualitzacions de l'octubre del 2012 de l'enquesta de població activa, en format ICS
BEGIN:VCALENDAR
VERSION:2.0
PRODID: -//Idescat.cat//NONSGML IdesCal 1.0//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VEVENT
UID:dif2012-epatnc201203269-1@idescat.cat
DTSTAMP:20120525T120258Z
DTSTART;VALUE=DATE:20121026
DURATION:P1D
SUMMARY:EPA III/2012 Cat.
DESCRIPTION:Enquesta de població activa III/2012 (Idescat)
STATUS:CONFIRMED
TRANSP:TRANSPARENT
CLASS:PUBLIC
END:VEVENT
END:VCALENDAR
Ex. 12: Actualitzacions de l'octubre del 2012 de l'enquesta de població activa, en format XML
<?xml version="1.0" encoding="utf-8" ?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
    <properties>
      <prodid>
        <text>-//Idescat.cat//NONSGML IdesCal 1.0//EN</text>
      </prodid>
      <version>
        <text>2.0</text>
      </version>
      <calscale>
        <text>GREGORIAN</text>
      </calscale>
      <method>
        <text>PUBLISH</text>
      </method>
    </properties>
    <components>
      <vevent>
        <properties>
          <uid>
            <text>dif2012-epatnc201203269-1@idescat.cat</text>
          </uid>
          <dtstamp>
            <date-time>20120525T121905Z</date-time>
          </dtstamp>
          <dtstart>
            <date>20121026</date>
          </dtstart>
          <duration>
            <duration>P1D</duration>
          </duration>
          <summary>
            <text>EPA III/2012 Cat.</text>
          </summary>
          <description>
            <text>Enquesta de població activa III/2012 (Idescat)</text>
          </description>
          <status>
            <text>CONFIRMED</text>
          </status>
          <transp>
            <text>TRANSPARENT</text>
          </transp>
          <class>
            <text>PUBLIC</text>
          </class>
        </properties>
      </vevent>
    </components>
  </vcalendar>
</icalendar>
Ex. 13: Actualitzacions de l'octubre del 2012 de l'enquesta de població activa, en format JSON
{
   version: "2.0",
   calscale: "GREGORIAN",
   method: "PUBLISH",
   vevent: [
      {
        uid: "dif2012-epatnc201203269-1@idescat.cat",
        dtstamp: "20120525T123209Z",
        dtstart: "20121026",
        duration: "P1D",
        summary: "EPA III/2012 Cat.",
        description: "Enquesta de població activa III/2012 (Idescat)",
        status: "CONFIRMED",
        transp: "TRANSPARENT",
        class: "PUBLIC"
      }
   ]
}

Quan la petició fa referència a períodes o estadístiques inexistents, la resposta inclourà un calendari sense esdeveniments.

2.2. Operació nodes

La resposta de l'operació nodes utilitza una estructura similar a la d'altres APIs de l'Idescat (vegeu per exemple l'API d'indicadors al dia.

Ex. 14: Relació d'estadístiques que es publiquen l'octubre del 2012, en format XML
<?xml version="1.0" encoding="utf-8" ?>
<cal
  version="1.00"
  lang="ca"
  o="nodes"
  n="17"
  p="t=201210"
>
    <v id="ADR">Indicadors de rendibilitat del sector hoteler</v>
    <v id="COMEST">Comerç amb l'estranger</v>
    <v id="EAS">Enquesta anual de serveis</v>
    <v id="ECLEM">Enquesta de clima empresarial</v>
    <v id="ECVHP">Enquesta de condicions de vida i hàbits de la població</v>
    <v id="EDSN">Estadística de divorcis, separacions i nul·litats</v>
    <v id="EFDE">Estadística del finançament i la despesa de l'ensenyament</v>
    <v id="ENL">Finançament públic de les entitats no lucratives</v>
    <v id="EPA">Enquesta de població activa</v>
    <v id="ETIC">Estadística del sector TIC</v>
    <v id="IASS">Indicadors d'activitat del sector serveis</v>
    <v id="IPC">Índex de preus de consum</v>
    <v id="IPI">Índex de producció industrial</v>
    <v id="IPRI">Índex de preus industrials</v>
    <v id="IVGS">Índex de vendes en grans superfícies</v>
    <v id="MNP">Moviment natural de la població</v>
    <v id="TURHOT">Indicadors d'activitat hotelera</v>
</cal>

Quan la petició fa referència a períodes o estadístiques inexistents, la resposta no inclourà elements v.

2.3. Errors

Les APIs de l'Idescat utilitzen codis de resposta normalitzats per indicar si la petició ha tingut èxit o si ha fracassat.