Skip to main content

Indicators of the day. API RSS

The Indicators of the day service provides basic information on a selection of indicators for Catalonia.

The use of this service requires acceptance of the Terms of use of Idescat's APIs.

Summary
Base URI https://api.idescat.cat/indicadors/v1/{operation}.{format}[?parameters]
HTTP Method GET
Response Formats xml, json, php
Version 1.00 (14/12/2009)
Shortcuts Request, Response, Examples
Operations dades, nodes

1. Request

1.1 Anatomy of requests

All requests must specify the service, version, operation and format. Version and operation are specific characteristics to each service. If nothing is stated to the contrary, the service supports the general response formats of Idescat's APIs. For more information, please consult the section Anatomy of requests in the general documentation of Idescat's APIs.

1.1.1 Service identifier and version

The Indicators of the day service is identified using the value indicators.

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

1.1.2 Operations

It allows two types of operation:

  • dades: returns data in the form of a time series for Catalonia and Spain of the chosen indicator. See section 1.2.1. 
    https://api.idescat.cat/indicadors/v1/dades.{…}
  • nodes: returns the tree of available indicators. See section 1.2.2. 
    https://api.idescat.cat/indicadors/v1/nodes.{…}

1.2 Specific parameters

The specific parameters ("variables") make it possible to select the information that will be returned by a certain operation of the Indicators of the day service. They can be specified as individual parameters or in a single parameter p (compact form). In this documentation, the compact form is always used.

To find out the general parameters available for any service, consult the Idescat's APIs documentation.

1.2.1 Operation dades

It permits selection of a fixed set of indicators or the most recent ones (whatever they are).

1.2.1.1 Predetermined indicators
  • i: list of the identifiers (separated by commas) of the indicators for which information will be returned.

To find out the identifiers of the different available indicators, use the operation nodes. Example 23 shows the current list of indicators and their identifiers.

If this variable of selection is present (even if it has no assigned value), the rest of the specific parameters are ignored.

Ex. 1: Series for Catalonia and Spain of the indicators 0801 and 0802, in XML format
https://api.idescat.cat/indicadors/v1/dades.xml?p=i/0801,0802
1.2.1.2 Latest indicators

It permits selection of indicators in accordance with the combination of three criteria:

  • tt: time passed. It permits selection of indicators in accordance with the days passed since they were published. Value 1 selects the indicators published today; 2 selects the indicators for today and yesterday; etc. The default value is 0 and indicates that the selection of indicators is not limited by the time passed.
  • max: maximum number of indicators. It limits the number of indicators shown, however much time has passed. The value 0 indicates that the selection of indicators is not limited by number. The default value is 6.
  • min: minimum number of indicators. It guarantees the display of a minimum number of indicators, however much time has passed. The default value is 6.

The indicators are returned in reverse chronological order.

Ex. 2: Indicators for the last 14 days (including today), but guaranteeing return of 3 indicators and limiting the result to a maximum of 10, in XML format
https://api.idescat.cat/indicadors/v1/dades.xml?p=tt/14;max/10;min/3
Ex. 3: Latest 3 indicators, in JSON format
https://api.idescat.cat/indicadors/v1/dades.json?p=tt/0;max/3;min/3
Ex. 4: : Indicators for the last 3 days (including today) without maximum or minimum number mattering, in serialised PHP format
https://api.idescat.cat/indicadors/v1/dades.php?p=tt/3;max/0;min/0
Ex. 5: All existing indicators without the time passed mattering, in XML format
https://api.idescat.cat/indicadors/v1/dades.xml?p=tt/0;max/0;min/0

Warning: The response time for this request can be slow. It is advisable to size requests to realistic information needs. One should never request all indicators without maintaining some kind of caché in the requesting machine.

1.2.2 Operation nodes

It returns a list of available indicators, with their identifier and a description, grouped into sections and subsections. The parameter i can be used to filter the sections being shown.

  • i: list of identifiers (separated by commas) of the sections for which information is returned. If not specified, all sections are shown.

To find out the identifiers of the currently available sections, use the operation nodes without specifying i.

Ex. 6: Tree of all indicators available, in JSON format with callback function ("func")
https://api.idescat.cat/indicadors/v1/nodes.json?callback=func
Ex. 7: Tree of the Basic indicators of Catalonia (2), in XML format
https://api.idescat.cat/indicadors/v1/nodes.xml?p=i/2

2. Response

To find out the HTTP response codes returned and the formats supported by any service, consult section 2 of Idescat's APIs.

2.1 Structure of the results

2.1.1 The indicadors root element

The root element (indicators) includes the following attributes:

  • version: version of the service.
  • lang: general language of the document. If the value of any textual element does not use this language, it will have its own lang attribute. The currently accepted values are ca (default value), es and en.
  • o: operation requested.
  • p: values assigned to the specific parameters, if there are any.
  • n: number of indicators or end nodes with information that have been included in the document. This number does not coincide with the number of elements returned when for some indicator or final node it has not been returned valid information.
Ex. 8: Attributes of the root element in an operation 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: Attributes of the root element in an operation nodes
<indicadors
 version="1.00"
 lang="ca"
 o="nodes"
 n="54"
 p="i=2"
>

2.1.2 The i elements of operation dades

The information for each indicator is included in the i element. As well as information for Catalonia, it may include comparative information for one or more geographical regions (at present, only Spain).

Ex. 10: i element of operation 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 General elements

The general elements are:

  • c: concept. For example, "CPI".
  • d: description of the indicator. For example, "Year to year change in the Consumer Price Index".
  • r: time reference. It contains at least one year (four digits). For example, "2009". The specification of the year can be followed by a hyphen. If there is a two-digit number after the hyphen this indicates the month ("2009-10": October 2009); if there is only one, this indicates the quarter ("2009-3": third quarter of 2009). Other reference periods are expressed in interval form (start and end date separated by a comma). For example, "2009-01,2009-05" indicates the period from January to May of 2009. The r element contains a title attribute that contains the time reference in brief text form in the general language lang. For example: "Jan/09".
  • u: this element is used to provide information about the indicator units. Its content can provide a very brief text that is concatenable to the value. At present, it is only used for the symbol "%"; in other cases, it is blank. This element contains an attribute s that has not been fully developed in the current version of the API.
  • l: link to the page of the indicator.
  • m: link to the page of the methodology of the indicator (as of April 24, 2018, the indicators stopped having a specific page on their methodology and, as a consequence, this element stopped being provided).
  • t: Text describing the type of indicator in the general language lang. The attribute i includes a coded version.
  • dc:date: date when indicator was updated (for example, "2009-03-08T11:05:00+00:00"). See the Dublin Core Metadata Initiative.
2.1.2.2 Specific elements of the geographic area

Indicators of the day is designed as a service that provides information for Catalonia. Additionally, it can offer the same information for other areas for comparative purposes. The information for Catalonia is contained in the following elements (which are always present):

  • Values

    The elements that contain values can have decimal points (for example, "10.5"). Missing values are indicated by "_".

    • v: value for the last period available. This value, that is also provided in the element ts, is also offered in v for convenience.
    • ts: time series. The values of the series, ordered from oldest to most recent, are separated by commas. In general, the series starts in the same reference period of the current data but one year earlier. Therefore, if the frequency of the data is monthly, 13 observations are included, and if it is quarterly, 5. In the case of annual values, these are offered for up to 5 years (or less if the series of available data is shorter). If there is no time series available, this element is not present.
  • Texts
    • s: text that expresses the source of the data.

If there is information available for other geographic areas, the elements vc, tsc and sc are included, which have the same meaning as the corresponding v, ts and s. These three new elements include an attribute g that indicates the geographic area (at the moment this is always equal to "es"). If the last value of the series of the area of comparison (tsc) is not available, vc will be present but with the value "_".

As at the moment, the source of the data (both for Catalonia and for Spain) is not translated, when requesting the result in a different language to Catalan both s and sc will include a lang attribute equal to "ca".

2.1.3 The v elements of the operation nodes

The indicators are grouped into sections and subsections. This hierarchy is expressed in a series of nested v elements. Each element has an identifier (id attribute). The end nodes (indicators) contain a text that describes the type of computation (desc attribute) and the indicator's update time (date attribute).

Ex. 11: v elements of operation 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

Idescat's APIs use standardised response codes to indicate whether the request has been successful or has failed. Requests to the API for Indicators of the day may be successful, but not return any of the requested indicators, maybe because they do not exist at the moment or have never existed (incorrect identifier), or maybe because the indicator is temporarily unavailable (for example, because it is being revised).

2.2.1 Operation dades

The i element of the indicator without information will provide the error attribute to indicate:

  • 403: Indicator exists but is temporarily unavailable. The c element will be the only descendent returned.
  • 404: Indicator inexistent at present (identifier not valid). The c element will contain a text explaining the error in the language of the request.

It is possible to know the number of indicators for which valid information has been returned thanks to the attribute n of the element indicators.

Ex. 12: Output of two erroneous indicators of the three requested
<?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 Operation nodes

The element v of existing indicators but that are temporarily unavailable will have an error attribute with value 403. Also, it will not have attributes desc and date.

Ex. 13: Fragment of tree with an indicator that is temporarily unavailable
<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>