Saltar al contenido principal

Calendario de difusión de resultados. API RSS

Esta API da acceso a la información del calendario del Idescat de difusión de resultados. Las fechas de publicación de las estadísticas que ofrece esta API permiten minimizar la cantidad de peticiones y hacer un uso más efectivo del resto de API.

La utilización de este servicio conlleva la aceptación de las condiciones de uso de las API del Idescat.

Resumen
URI base https://api.idescat.cat/cal/v1/{operación}.{formato}[?parámetros]
Método HTTP GET
Formatos de la respuesta xml, json, php, txt, ical
Versión 1.00 (01/06/2012)
Atajos Petición, Respuesta
Operaciones dades, nodes

1. Petición

1.1. Características básicas

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

Adicionalmente, la operación dades puede devolver el calendario en formato iCalendar. Éste es un estándar que en esta API puede solicitarse especificando como formato txt o ics. La única diferencia es que, en el primer caso y por cuestión de homogeneidad, la cabecera de la respuesta declarará el tipo del contenido como text/plain y en el segundo, de acuerdo con el estándar, como text/calendar (y la disposición del contenido será attachment y se facilitará un nombre del fichero).

1.1.1. Identificador del servicio y versión

El identificador de este servicio es cal.

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

1.1.2. Operaciones

Este servicio admite dos tipos de operaciones:

  • dades: Devuelve los acontecimientos incluidos en el calendario de difusión.
    https://api.idescat.cat/cal/v1/dades.{…}
  • nodes: Devuelve la relación de estadísticas incluidas en el calendario de difusión.
    https://api.idescat.cat/cal/v1/nodes.{…}

1.2. Parámetros específicos

Este servicio soporta los parámetros generales (idioma y codificación) de las API del Idescat.

Los parámetros específicos permiten escoger la información que devolverá una determinada operación del servicio. Se pueden especificar como parámetros individuales o en un único parámetro p (forma compacta).

1.2.1. Operación dades

La operación dades devuelve los acontecimientos de difusión de resultados estadísticos del Idescat con día confirmado.

1.2.1.1. Filtro t

Este parámetro sirve para especificar el periodo temporal del cual se quieren recuperar acontecimientos. Se recomienda especificar siempre este parámetro. Si no se especifica, se devolverán los acontecimientos del conjunto del año más reciente para el cual se dispone de calendario de difusión.

Es importante advertir que este parámetro selecciona los acontecimientos según la fecha de publicación de los resultados, no según el periodo al cual se refieren.

Hay que tener en cuenta que el primer año del cual se dispone de calendario es el 2012.

Ej. 1: Calendario de difusión del año 2012 en formato XML
https://api.idescat.cat/cal/v1/dades.xml?t=2012&lang=es
Ej. 2: Calendario de difusión de octubre del 2012 en formato JSON
https://api.idescat.cat/cal/v1/dades.json?t=201210&lang=es
Ej. 3: Calendario de difusión del 23 de octubre del 2012 en formato ICS
https://api.idescat.cat/cal/v1/dades.ics?t=20121023&lang=es

Este parámetro también permite especificar intervalos usando el guión.

Ej. 4: Calendario de difusión de octubre y noviembre del 2012 en formato PHP serializado
https://api.idescat.cat/cal/v1/dades.php?t=201210-201211&lang=es
Ej. 5: Calendario de difusión de la semana del 22 de octubre en formato texto
https://api.idescat.cat/cal/v1/dades.txt?t=20121022-20121028&lang=es
1.2.1.2. Filtro id

Se puede utilizar el parámetro id para solicitar el calendario de una determinada estadística.

Ej. 6: Calendario de difusión del año 2012 de la encuesta de población activa (EPA) en formato JSON
https://api.idescat.cat/cal/v1/dades.json?t=2012&id=epa&lang=es

Para obtener la relación de estadísticas disponibles en un periodo concreto se puede usar la operación nodes.

1.2.2. Operación nodes

La operación nodes devuelve la relación de estadísticas que se han publicado o se publicarán en un determinado periodo y permite conocer los valores válidos del parámetro id de la operación dades.

1.2.2.1. Filtro t

Este parámetro sirve para especificar el periodo temporal del cual se quiere recuperar la denominación y el código de las estadísticas que se difunden. Se recomienda especificar siempre este parámetro. Si no se especifica, se devolverá la relación de estadísticas que tienen alguna difusión de resultados durante el conjunto del año más reciente de la cual se disponga de calendario.

Ej. 7: Lista de estadísticas que tienen difusión de resultados durante el año 2012 y sus códigos, en formato XML
https://api.idescat.cat/cal/v1/nodes.xml?t=2012&lang=es

Para conocer la sintaxis y todas las posibilidades de este parámetro se puede consultar el apartado correspondiente de la operación dades.

Ej. 8: Lista de estadísticas que tienen difusión de resultados entre el 23 de octubre y el 23 de noviembre del 2012 y sus códigos, en formato JSON
https://api.idescat.cat/cal/v1/nodes.json?t=20121023-20121123&lang=es
1.2.2.2. Filtro id

Se puede utilizar el parámetro id para validar si una determinada estadística se actualizará en cierto periodo de tiempo. También se puede usar para obtener la denominación de una estadística a partir de su código.

Ej. 9: Estadística que tiene el código IPRI con difusión de resultados durante el año 2012, en formato XML
https://api.idescat.cat/cal/v1/nodes.xml?t=2012&id=ipri&lang=es

En el caso de la operación nodes, el parámetro id admite una lista de valores separados por una coma (esta opción no está disponible en la invocación sin operación).

Ej. 10: Estadísticas que tienen los códigos IPRI y IPI con difusión de resultados durante el año 2012, en formato XML
https://api.idescat.cat/cal/v1/nodes.xml?t=2012&id=ipri,ipi&lang=es

1.3. Invocación sin operación

Por cuestiones de amigabilidad, esta API admite peticiones con una sintaxis que no requiere especificar operaciones (se puede consultar la documentación general de las API del Idescat en el apartado 1.4. Invocación sin operación).

  • Calendario de difusión de resultados del año 2012, en formato XML
    https://api.idescat.cat/cal/v1/calendari/2012.xml?lang=es
  • Calendario de difusión de resultados de diciembre del 2012, en formato JSON
    https://api.idescat.cat/cal/v1/calendari/201212.json?lang=es
  • Calendario de difusión de resultados del año 2012 del índice de producción industrial (IPI), en formato ICS
    https://api.idescat.cat/cal/v1/calendari/2012/ipi.ics?lang=es
  • Estadísticas que se publican en el año 2012, en formato XML
    https://api.idescat.cat/cal/v1/estadistiques/2012.xml?lang=es
  • Estadísticas que se publican en el año 2012 con código IPROSS, en formato JSON
    https://api.idescat.cat/cal/v1/estadistiques/2012/ipross.json?lang=es

2. Respuesta

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

La estructura de la respuesta de la operación dades se basa en el estándar de texto iCalendar. En el caso del formato XML, se utiliza el mapeo estándar de iCalendar llamado xCal.

Ej. 11: Actualizaciones de octubre del 2012 de la encuesta de población activa, en formato 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:Encuesta de población activa III/2012 (Idescat)
STATUS:CONFIRMED
TRANSP:TRANSPARENT
CLASS:PUBLIC
END:VEVENT
END:VCALENDAR
Ej. 12: Actualizaciones de octubre del 2012 de la encuesta de población activa, en formato 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>Encuesta de población 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>
Ej. 13: Actualizaciones de octubre del 2012 de la encuesta de población activa, en formato 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: "Encuesta de población activa III/2012 (Idescat)",
        status: "CONFIRMED",
        transp: "TRANSPARENT",
        class: "PUBLIC"
      }
   ]
}

Cuando la petición se refiere a periodos o estadísticas inexistentes, la respuesta incluirá un calendario sin acontecimientos.

2.2. Operación nodes

La respuesta de la operación nodes utiliza una estructura similar a la de otras API del Idescat (por ejemplo el API de indicadores al día).

Ej. 14: Relación de estadísticas que se publican en octubre del 2012, en formato XML
<?xml version="1.0" encoding="utf-8" ?>
<cal
  version="1.00"
  lang="es"
  o="nodes"
  n="17"
  p="t=201210"
>
    <v id="ADR">Indicadores de rentabilidad del sector hotelero</v>
    <v id="COMEST">Comercio con el extranjero</v>
    <v id="EAS">Encuesta anual de servicios</v>
    <v id="ECLEM">Encuesta de clima empresarial</v>
    <v id="ECVHP">Encuesta de condiciones de vida y hábitos de la población</v>
    <v id="EDSN">Estadística de divorcios, separaciones y nulidades</v>
    <v id="EFDE">Encuesta de financiación y gastos de la enseñanza</v>
    <v id="ENL">Financiación pública de las entidades no lucrativas</v>
    <v id="EPA">Encuesta de población activa</v>
    <v id="ETIC">Estadística del sector TIC</v>
    <v id="IASS">Indicadores de actividad del sector servicios</v>
    <v id="IPC">Índice de precios de consumo</v>
    <v id="IPI">Índice de producción industrial</v>
    <v id="IPRI">Índice de precios industriales</v>
    <v id="IVGS">Índice de ventas en grandes superficies</v>
    <v id="MNP">Movimiento natural de la población</v>
    <v id="TURHOT">Indicadores de actividad hotelera</v>
</cal>

Cuando la petición se refiere a periodos o estadísticas inexistentes, la respuesta no incluirá elementos v.

2.3. Errores

Las API del Idescat utilizan códigos de respuesta normalizados para indicar si la petición ha sido exitosa o si ha fracasado.