Skip to main content

The municipality in figures. API RSS

This API provides basic comparative statistical information on municipalities, counties and Catalonia. Idescat offers this same information in the section The municipality in figures.

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

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

1. Request

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.

1.1.1. Identifier of service and version

The identifier of this service is emex.

https://api.idescat.cat/emex/v1/{…}?lang=en

1.1.2. Operations

This service admits two types of operation:

  • dades: Returns basic statistics for the territorial level selected (municipality or county) and the same information for higher territorial levels (county and Catalonia). 
    https://api.idescat.cat/emex/v1/dades.{…}?lang=en
  • nodes: Returns the territorial levels included in the service. 
    https://api.idescat.cat/emex/v1/nodes.{…}?lang=en

1.2. Specific parameters

This service supports the general parameters (language and encoding) of Idescat APIs. As well as the languages offered generally, this service also accepts Occitan (lang=oc).

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 parameter p (compact form).

1.2.1. Operation dades

The dades operation returns basic statistics for the territorial level selected (municipality or county) and the same information for higher territorial levels (county and Catalonia).

1.2.1.1. id filter

This parameter is used to specify the territorial level (municipality or county) according to its official code.

Ex. 1: Basic statistical information on Abella de la Conca (250019), el Pallars Jussà and Catalonia
https://api.idescat.cat/emex/v1/dades.xml?id=250019&lang=en

To obtain a list of municipalities and counties in Catalonia and their official codes, use the nodes operation.

1.2.1.2. i filter

If you do not want all of the information for a territorial level, you can use the parameter i to specify, separated by a comma, the indicators that are to be included in the response.

Ex. 2: Total, male and female population data for Abrera, el Baix Llobregat and Catalonia
https://api.idescat.cat/emex/v1/dades.xml?id=080018&i=f171,f36,f42&lang=en

The identifiers of the indicators that appear in the id attribute of the f elements of the complete response (i.e. without specifying parameter i) of the dades operation.

Data can also be requested for a limited number of indicators (5) for all territorial areas.

Ex. 3: Total, male and female population data for all the municipalities, counties and Catalonia
https://api.idescat.cat/emex/v1/dades.xml?i=f171,f36,f42&lang=en

Note that some indicators can have several sources. Given that this API always uses the common source for the areas included in the response, the source of a certain indicator for a certain municipality may not be the same in requests where the selected territorial areas are different.

The dades operation must mandatorily include the id or the i parameter. If it does not include either, data will not be returned for any indicator.

1.2.1.3. tipus filter

The tipus parameter can be used in requests without the id parameter in order to limit the areas included in the response in accordance with the following typology:

  • cat: Catalonia
  • com: Counties
  • mun: Municipalities

These values can be linked separated by commas. By default, tipus is equal to cat,com,mun.

1.2.2. Operation nodes

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

Ex. 4: Hierarchical list of geographic units (Catalonia, counties and municipalities) and their codes in JSON format
https://api.idescat.cat/emex/v1/nodes.json?lang=en
1.2.2.1. tipus filter

The tipus parameter in the nodes operation has the same meaning and accepts the same values as in the dades operation.

Ex. 5: List of counties and their codes in JSON format
https://api.idescat.cat/emex/v1/nodes.json?tipus=com

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

  • List of geographic units available in XML format 
    https://api.idescat.cat/emex/v1/geo.xml?lang=en
  • List of the counties of Catalonia en XML format 
    https://api.idescat.cat/emex/v1/geo.xml?tipus=com&lang=en
  • Information on the indicador f171 (population) for Catalonia and its counties in JSON format 
    https://api.idescat.cat/emex/v1/geo.json?i=f171&tipus=cat,com&lang=en
  • Complete information on geographic unit 01 (Alt Camp) in XML format 
    https://api.idescat.cat/emex/v1/geo/01.xml?lang=en
  • Complete information on geographic unit 170010 (Agullana) in JSON format 
    https://api.idescat.cat/emex/v1/geo/170010.json?lang=en
  • Information on the indicators f328 (longitude) and f329 (latitude) of geographic unit 170010 (Agullana) in serialised PHP format 
    https://api.idescat.cat/emex/v1/geo/170010.php?i=f328,f329&lang=en

2. Response

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

2.1. The fitxes root element

The root element (fitxes) appears in all responses, whatever the operation. It includes the following attributes:

  • version: version of the service.
  • lang: general language of the document. This service admits the value oc, as well as ca (default value), es and en.
  • o: operation requested.
  • p: values assigned to specific parameters, if there are any.
Ex. 6: Attributes of the root element in a dades operation
<fitxes
   version="1.00"
   lang="en"
   o="dades"
   p="id=080155"
>

2.2. Operation dades

The structure of the response to the dades operation depends on whether a list of indicators (i) has been specified or not. In both cases, the response contains the element cols.

2.2.1. Columns (cols)

The element cols contains information on the territorial areas on which statistical information is included. For each level, this element contains an element col with its code (value of attribute id) and its name (content of the element). The territorial level specifies the scheme attribute: municipality (mun), county (com) or Catalonia (ca).

Ex. 7: cols element in a dades operation
<cols>
   <col id="080155" scheme="mun">Badalona</col>
   <col id="13" scheme="com">Barcelonès</col>
   <col id="09" scheme="ca">Catalonia</col>
</cols>

2.2.2. Response with all indicators

2.2.2.1. Groups (g), tables (t), rows (f), names (c) and value vectors (v)

When all of the available indicators are requested for a certain level, these are included in a gg element (set of groups). Within this element, the information is presented grouped into different levels: groups, tables and rows.

Each group (g) contains an identifier (attribute id), a name (c) and, either a set of tables (tt) or otherwise a new set of groups (gg). This latter possibility is not currently used in the API on The municipality in figures. Each table (t) has one identifier (attribute id), a name (c) and a set of rows (or indicators) (ff). And each row (f) has an identifier (attribute id), a name (c) and a values vector (v).

The values vector (v) contains as many figures separated by commas as there are columns (col). The decimals are indicated using a point and the remaining values with "_".

Ex. 8: A group g and its lower levels
<g id="g158">
    <c>Movement of the population</c>
    <tt>
        <t id="t164">
            <c>Births. By sex</c>
            <ff>
                <f id="f185">
                    <c>Boys</c>
                    <v>1386,12043,45984</v>
                    ...
                </f>
                <f id="f186">
                    <c>Girls</c>
                    <v>1348,11160,43040</v>
                    ...
                </f>
                <f id="f187">
                    <c>Total</c>
                    <v>2734,23203,89024</v>
                    ...
                </f>
            </ff>
            ...
        </t>
        ...
    </tt>
</g>
2.2.2.2. Alternative name (calt)

The names of (c) tables (t) and rows (f) can have an alternative name (calt). In the case of tables calt offers a name that is generally shorter than c, and is appropriate for a list of contents of the group. In the case of rows, as c already offers a name that is only comprehendible in the context of a table, calt provides a short name that is useful for presenting the rows separately (as indicators), rather than grouped in a table.

Ex. 9: The calt element of tables (t) and rows (f)
<t id="t164">
    <c>Births. By sex</c>
    <calt>Births</calt>
    <ff>
        <f id="f185">
            <c>Boys</c>
            <calt>Births of boys</calt>
            <v>1386,12043,45984</v>
        </f>
        <f id="f186">
            <c>Girls</c>
            <calt>Births of girls</calt>
            <v>1348,11160,43040</v>
        </f>
        <f id="f187">
            <c>Total</c>
            <calt>Births</calt>
            <v>2734,23203,89024</v>
        </f>
    </ff>
    ...
</t>
2.2.2.3. Units (u), time reference (r) and date updated (updated)

The values vector (v) of each row (f) of a table (t) is expressed in units (u), is referred to a time period (r) or has a date updated (updated).

The rows in a table usually share the content of all or some of these elements. In these cases, the API returns the element as a result of the table (t) rather than it being repeated in each row (f).

The u content provides an expressive literal of the measurement units to complement the name of the table or row. When this unit's name makes it obvious what it is (e.g. "Births"), the u element does not appear.

Ex. 10: Row (f) with units (u)
<f id="f3">
    <c>GDP pm per inhabitant</c>
    <calt>GDP per inhabitant</calt>
    <v>18.1,30.7,27.3</v>
    <u>Thousands of euros</u>
</f>

All of the data in this service offers a yearly time reference that expressed as four digits as the content of an r. element. This element always appears, whether it is the result of f or the result of t.

All of the data in this service has a date updated that appears as the content of the element updated. This element always appears, whether it is the result of f or the result of t. The data format used can be seen in the following example (see the RFC3339 for an interpretation of it).

Ex. 11: Common r and upated elements to all f of a table t
<g id="g158">
    <c>Movement of the population</c>
    <tt>
        <t id="t164">
            <c>Births. By sex</c>
            <calt>Births</calt>
            <ff>
                <f id="f185">
                    ...
                </f>
                <f id="f186">
                    ...
                </f>
                <f id="f187">
                    ...
                </f>
            </ff>
            <r>2008</r>
            <updated>2010-06-11T10:00:00+00:00</updated>
            ...
        </t>
        ...
    </tt>
    ...
</g>
2.2.2.4. Source (s) and link (l)

All of the tables have an associated text description of the source of the information (s) and, if available, a link to the table it was extracted from (l), i.

Ex. 12: Common r and upated elements to all f rows of a table t
<t id="t176">
    <c>Geographic indicators</c>
    <ff>
        <f id="f258">
            <c>Altitude</c>
            <calt>Altitude</calt>
            <v>105,_,_</v>
            <u>m</u>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </f>
        <f id="f259">
            <c>UTM coordinates x</c>
            <calt>UTM coordinates x</calt>
            <v>408471,_,_</v>
            <u>m</u>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </f>
        <f id="f260">
            <c>UTM coordinates y</c>
            <calt>UTM coordinates y</calt>
            <v>4596983,_,_</v>
            <u>m</u>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </f>
    </ff>
    <r>2009</r>
	<s>Idescat, based on data from the Institut Cartogràfic de Catalunya.</s>
    <l>
          https://www.idescat.cat/pub/?id=inddt&amp;n=396&amp;geo=muni080018&amp;lang=en
    </l>
</t>

2.2.3. Response with a selection of indicators

The API enables the selection of the indicators that are to be included in the response with parameter i. In this case, rather than the element gg, the indicadors element appears.

This element includes the information on the selected indicators observing a structure based on the API Indicators of the day where the element dc:date has been substituted by updated and v is a vector rather than a unique value. The name of the indicator (c) that appears is, in the requests where i, has not been specified, the calt content of the row (f). Finally, t includes the identifier and name of the table to which the indicator belongs.

Ex. 13: Result of the dades operation of a request for two indicators, one incorrect ("156") and the other correct ("f2"), for Abrera
<?xml version="1.0" encoding="utf-8"?>
<fitxes version="1.00" lang="en" o="dades" n="1" p="id=080018;i=156,f2">
    <cols>
        <col id="080018" scheme="mun">Abrera</col>
        <col id="11" scheme="com">Baix Llobregat</col>
        <col id="09" scheme="ca">Catalonia</col>
    </cols>
    <indicadors>
        <i id="156" error="404">
            <c>Indicador not found</c>
        </i>
        <i id="f2">
            <c>GDP pm</c>
            <v>608.5,21576.4,195857.8</v>
            <u>Millions of euros</u>
            <r>2006</r>
            <s>Idescat.</s>
            <t id="t1">Gross domestic product at market prices (base 2000)</t>
            <l>
                 https://www.idescat.cat/pub/?id=pibc&amp;n=8276&amp;geo=muni080018&amp;lang=en
            </l>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </i>
    </indicadors>
</fitxes>
Ej. 14: Result of the dades operation of a request for an indicator ("f187"), by counties
<?xml version="1.0" encoding="utf-8"?>
<fitxes version="1.00" lang="en" o="dades" n="1" p="i=f187;tipus=com">
    <cols>
        <col id="01" scheme="com">Alt Camp</col>
        <col id="02" scheme="com">Alt Empordà</col>
        <col id="03" scheme="com">Alt Penedès</col>
        <col id="04" scheme="com">Alt Urgell</col>
        <col id="05" scheme="com">Alta Ribagorça</col>
        <col id="06" scheme="com">Anoia</col>
        <col id="07" scheme="com">Bages</col>
        <col id="08" scheme="com">Baix Camp</col>
        <col id="09" scheme="com">Baix Ebre</col>
        <col id="10" scheme="com">Baix Empordà</col>
        <col id="11" scheme="com">Baix Llobregat</col>
        <col id="12" scheme="com">Baix Penedès</col>
        <col id="13" scheme="com">Barcelonès</col>
        <col id="14" scheme="com">Berguedà</col>
        <col id="15" scheme="com">Cerdanya</col>
        <col id="16" scheme="com">Conca de Barberà</col>
        <col id="17" scheme="com">Garraf</col>
        <col id="18" scheme="com">Garrigues</col>
        <col id="19" scheme="com">Garrotxa</col>
        <col id="20" scheme="com">Gironès</col>
        <col id="21" scheme="com">Maresme</col>
        <col id="22" scheme="com">Montsià</col>
        <col id="23" scheme="com">Noguera</col>
        <col id="24" scheme="com">Osona</col>
        <col id="25" scheme="com">Pallars Jussà</col>
        <col id="26" scheme="com">Pallars Sobirà</col>
        <col id="27" scheme="com">Pla d'Urgell</col>
        <col id="28" scheme="com">Pla de l'Estany</col>
        <col id="29" scheme="com">Priorat</col>
        <col id="30" scheme="com">Ribera d'Ebre</col>
        <col id="31" scheme="com">Ripollès</col>
        <col id="32" scheme="com">Segarra</col>
        <col id="33" scheme="com">Segrià</col>
        <col id="34" scheme="com">Selva</col>
        <col id="35" scheme="com">Solsonès</col>
        <col id="36" scheme="com">Tarragonès</col>
        <col id="37" scheme="com">Terra Alta</col>
        <col id="38" scheme="com">Urgell</col>
        <col id="39" scheme="com">Val d'Aran</col>
        <col id="40" scheme="com">Vallès Occidental</col>
        <col id="41" scheme="com">Vallès Oriental</col>
    </cols>
    <indicadors>
        <i id="f187">
            <c>Births</c>
            <v>
                   518, 1592, 1391, 175, 38, 1496, 2165, 2314, 853, 1520, 9480, 1198, 22075, 340,
                   176, 197, 1515, 181, 576, 2575, 4945, 708, 419, 1922, 111, 66, 454, 437, 79, 194,
                   227, 266, 2418, 1810, 158, 3145, 87, 412, 102, 10859, 4821
            </v>
            <r>2010</r>
            <s>Idescat. Natural movement of population.</s>
            <t id="t164">Births. By sex</t>
            <updated>2011-10-13T10:00:00+00:00</updated>
        </i>
    </indicadors>
</fitxes>

2.3. Operation nodes

The municipalities are grouped into counties and these are grouped under the territorial level of Catalonia. This hierarchy is expressed as a series of overlapping v elements. Each of these elements has an attribute id with the code for the territorial level and an attribute scheme that specifies the territorial level: municipality ("mun"), county ("com") or Catalonia ("ca").

<?xml version="1.0" encoding="utf-8"?>
<fitxes version="1.00" lang="en" o="nodes" p="tipus=cat,com,mun">
    <v id="09" scheme="ca">Catalunya
        <v id="01" scheme="com">Alt Camp
            <v id="430017" scheme="mun">Aiguamúrcia</v>
            <v id="430056" scheme="mun">Alcover</v>
            <v id="430108" scheme="mun">Alió</v>
            <v id="430347" scheme="mun">Bràfim</v>
            <v id="430363" scheme="mun">Cabra del Camp</v>
            <v id="430593" scheme="mun">Figuerola del Camp</v>
            <v id="430666" scheme="mun">Garidells, els</v>
            <v id="430803" scheme="mun">Masó, la</v>
            <v id="430831" scheme="mun">Milà, el</v>
            <v id="430897" scheme="mun">Montferri</v>
            <v id="430918" scheme="mun">Mont-ral</v>
            <v id="430982" scheme="mun">Nulles</v>
            <v id="431080" scheme="mun">Pla de Santa Maria, el</v>
            <v id="431135" scheme="mun">Pont d'Armentera, el</v>
            <v id="431191" scheme="mun">Puigpelat</v>
            <v id="431205" scheme="mun">Querol</v>
            <v id="431248" scheme="mun">Riba, la</v>
            <v id="431325" scheme="mun">Rodonyà</v>
            <v id="431346" scheme="mun">Rourell, el</v>
            <v id="431606" scheme="mun">Vallmoll</v>
            <v id="431613" scheme="mun">Valls</v>
            <v id="431652" scheme="mun">Vilabella</v>
            <v id="431704" scheme="mun">Vila-rodona</v>
        </v>
        <v id="02" scheme="com">Alt Empordà
            <v id="170010" scheme="mun">Agullana</v>
            <v id="170031" scheme="mun">Albanyà</v>
            <v id="170059" scheme="mun">Far d'Empordà, el</v>
            ...
        </v>
        ...
    </v>
</fitxes>

2.4. Errors

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