Advance Release Calendar. API

1.1. Basic characteristics

Every request must by obligation specify the service, version, operation and format. Version and operation are specific characteristics of each service. This service supports the formats for general responses of Idescat APIs. For more information, see the Anatomy of requests sections of the general documentation on Idescat APIs.

In addition, the dades operation returns the calendar in iCalendar format. This is a standard that in this API may be requested specifying txt or ics as a format. The only difference is that, in the first case and for an homogeneity purpose, the headline of the response will state the content type as text/plain and in the second, in accordance with the standard, as text/calendar (and the disposition of the contents will be attachment and a filename will be facilitated).

1.1.1. Identifier of service and version

The identifier of this service is cal.

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

1.1.2. Operations

This service admits two types of operation:

• dades: Returns the events included in the Advance Release Calendar.

  http://api.idescat.cat/cal/v1/dades.{…}

• nodes: Returns the list of statistics included in the Advance Release Calendar.

  http://api.idescat.cat/cal/v1/nodes.{…}

1.2. Specific parameters

This service supports the general parameters (language and encoding) of Idescat APIs.

The specific parameters can be used to choose the information that will be returned by a certain service operation. These can be specified as individual parameters or as a unique p parameter (compact form).

1.2.1. Operation dades

The dades operation returns the events of the Idescat's statistics results dissemination with confirmed date.

1.2.1.1. t filter

This parameter is used to specify the period from which you want to recover events. It is recommended to specify this parameter always. Otherwise, all the events of the most recent year available a Advance Release Calendar will be returned.

It is important to note that this parameter selects events according to the date the result will be published, and not to the period to which they refer.

2012 is the first year the calendar is available.

Ex. 1: 2012 Advance Release Calendar, in XML format

http://api.idescat.cat/cal/v1/dades.xml?t=2012&lang=en

Ex. 2: Advance Release Calendar on October 2012, in JSON format

http://api.idescat.cat/cal/v1/dades.json?t=201210&lang=en

Ex. 3: Advance Release Calendar on October 23, 2012, in ICS format

http://api.idescat.cat/cal/v1/dades.ics?t=20121023&lang=en

This parameter also permits specifying intervals using the hyphen.

Ex. 4: Advance Release Calendar on October and November 2012, in serialised PHP format

http://api.idescat.cat/cal/v1/dades.php?t=201210-201211&lang=en

Ex. 5: Advance Release Calendar on week 43, 2102, in text format

http://api.idescat.cat/cal/v1/dades.txt?t=20121022-20121028&lang=en

1.2.1.2. id filter

The id parameter may be used to request a particular statistic calendar.

Ex. 6: 2012 Advance Release Calendar of the Active Population Survey (EPA), in JSON format

http://api.idescat.cat/cal/v1/dades.json?t=2012&id=epa&lang=en

To obtain the list of available statistics in a particular period, use the nodes operation.

1.2.2. Operation nodes

The nodes operation returns the territorial levels included in the service and provides information on the valid values of the parameter id of the dades operation.

1.2.2.1. t filter

This parameter is used to specify the time period from which to recover the name and the code of the disseminated statistics. It is recommended to specify this parameter always. Otherwise, all the events of the most recent year available Advance Release Calendar will be returned.

Ex. 7: List of statistics with disseminated results during 2012 and their codes, in XML format

http://api.idescat.cat/cal/v1/nodes.xml?t=2012&lang=en

See the section corresponding to the dades operation for the syntax and all the options of this parameter.

Ex. 8: List of statistics with disseminated results between October 23 and November 23, 2012, and their codes, in JSON format

http://api.idescat.cat/cal/v1/nodes.json?t=20121023-20121123&lang=en

1.2.2.2. id filter

This parameter is used to check the availability of updates of a particular statistic in a certain period of time. It is also used to obtain the name of a particular statistic from its code.

Ex. 9: Statistics with IPRI code with results disseminated during 2012, in XML format

http://api.idescat.cat/cal/v1/nodes.xml?t=2012&id=ipri&lang=en

In the case of the nodes operation, the id parameter accepts a list of values separated by comma (this options is not available in the invocation without operation).

Ex. 10: Statistics with IPRI and IPI codes with results disseminated during 2012, in XML format

http://api.idescat.cat/cal/v1/nodes.xml?t=2012&id=ipri,ipi

1.3. Invocation without operation

For reasons of user-friendliness, this API accepts requests with a syntax that does not require the specification of operations (see the general documentation on Idescat APIs, section 1.4. Invocation without operation).

• 2012 Advance Release Calendar, in XML format

  http://api.idescat.cat/cal/v1/calendari/2012.xml?lang=en

• Advance Release Calendar on December 2012, in JSON format

  http://api.idescat.cat/cal/v1/calendari/201212.json?lang=en

• 2012 Advance Release Calendar for Industrial Production Index (IPI), in ICS format

  http://api.idescat.cat/cal/v1/calendari/2012/ipi.ics?lang=en

• 2012 published statistics, in XML format

  http://api.idescat.cat/cal/v1/estadistiques/2012.xml?lang=en

• 2012 published statistics for IPROSS code, in JSON format

  http://api.idescat.cat/cal/v1/estadistiques/2012/ipross.json?lang=en

In order to find out the HTTP response codes HTTP returned and the formats supported by any service, see section 2 of Idescat APIs.

2.1. Operation dades

The structure of the response to dades operation is based on the iCalendar text standard. In the case of the XML format, the structure is based on the iCalendar standard mapping called xCal.

Ex. 11: Advance Release Calendar for Active Population Survey on October 2012, in ICS format

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:Active Population Survey III/2012 (Idescat)
STATUS:CONFIRMED
TRANSP:TRANSPARENT
CLASS:PUBLIC
END:VEVENT
END:VCALENDAR

Ex. 12: Advance Release Calendar for Active Population Survey on October 2012, in XML format

<?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>Active Population Survey 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: Advance Release Calendar for Active Population Survey on October 2012, in JSON format

{
   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: "Active Population Survey III/2012 (Idescat)",
        status: "CONFIRMED",
        transp: "TRANSPARENT",
        class: "PUBLIC"
      }
   ]
}

When the request is related to nonexistent periods or statistics, the response will include a calendar without events.

2.2. Operation nodes

The nodes operation uses similar structures to other Idescat APIs (for instance, indicators of the day).

Ex. 14: List of published statistics on October 2012, in XML format

<?xml version="1.0" encoding="utf-8" ?>
<cal
  version="1.00"
  lang="en"
  o="nodes"
  n="17"
  p="t=201210"
>
    <v id="ADR">Indicators of Hotel Sector Profitability</v>
    <v id="COMEST">Foreign Trade from Catalonia</v>
    <v id="EAS">Annual Survey of Services</v>
    <v id="ECLEM">Business Climate Survey</v>
    <v id="ECVHP">Survey on Living Conditions and Habits of the Population</v>
    <v id="EDSN">Statistics on Divorces, Separations and Annulments</v>
    <v id="EFDE">Survey on Finance and Expenditure in Education</v>
    <v id="ENL">Public Finance of non Profit Entities</v>
    <v id="EPA">Active Population Survey</v>
    <v id="ETIC">Statistics on the ICT Sector</v>
    <v id="IASS">Indicators of Service Sector Activity</v>
    <v id="IPC">Consumer Price Index</v>
    <v id="IPI">Industrial Production Index</v>
    <v id="IPRI">Industrial Price Index</v>
    <v id="IVGS">Large Stores Sales Index</v>
    <v id="MNP">Natural movement of the population</v>
    <v id="TURHOT">Indicators of Hotel Activity</v>
</cal>

When the request is related to nonexistent periods or statistics, the response will not include v elements.

2.3. Errors

Idescat APIs use standardised response codes to show whether the request has been successful or has failed.