El municipi en xifres. API

Aquesta API dona accés a informació estadística bàsica comparativa de municipis, comarques i Catalunya. L'Idescat difon aquesta mateixa informació a la secció El municipi en xifres.

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

1. Petició
2. Resposta

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.

1.1.1. Identificador del servei i versió

L'identificador d'aquest servei és emex.

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

1.1.2. Operacions

Aquest servei admet dos tipus d'operacions:

dades: Retorna estadístiques bàsiques de l'àmbit territorial seleccionat (municipi o comarca) i la mateixa informació per als àmbits superiors previstos (comarca i Catalunya).
```
https://api.idescat.cat/emex/v1/dades.{…}
```
nodes: Retorna els àmbits territorials previstos en el servei.
```
https://api.idescat.cat/emex/v1/nodes.{…}
```

1.2. Paràmetres específics

Aquest servei suporta els paràmetres generals (idioma i codificació) de les APIs de l'Idescat. A més dels idiomes acceptats amb caràcter general, aquest servei admet l'occità (lang=oc).

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 estadístiques bàsiques de l'àmbit territorial seleccionat (municipi o comarca) i la mateixa informació per als àmbits superiors previstos (comarca i Catalunya).

1.2.1.1. Filtre `id`

Aquest paràmetre serveix per especificar l'àmbit territorial (municipi o comarca) segons el seu codi oficial.

Ex. 1: Informació estadística bàsica d'Abella de la Conca (250019), el Pallars Jussà i Catalunya

https://api.idescat.cat/emex/v1/dades.xml?id=250019

Per obtenir la relació de municipis i comarques de Catalunya i els seus codis oficials, utilitzeu l'operació nodes.

1.2.1.2. Filtre `i`

Si no es vol tota la informació d'un àmbit territorial, es pot utilitzar el paràmetre i per especificar, separats per comes, els indicadors que s'han d'incloure a la resposta.

Ex. 2: Dades de població total, masculina i femenina d'Abrera, el Baix Llobregat i Catalunya

https://api.idescat.cat/emex/v1/dades.xml?id=080018&i=f171,f36,f42

Els identificadors dels indicadors apareixen a l'atribut id dels elements f de la resposta completa (és a dir, sense especificació del paràmetre i) de l'operació dades.

També es poden sol·licitar les dades d'un nombre limitat d'indicadors (5) per a tots els àmbits territorials.

Ex. 3: Dades de població total, masculina i femenina de tots els municipis, comarques i Catalunya

https://api.idescat.cat/emex/v1/dades.xml?i=f171,f36,f42

Cal tenir en compte que alguns indicadors poden disposar de diverses fonts. Atès que aquesta API utilitza sempre la font comuna per als àmbits inclosos en la resposta, la font d'un determinat indicador per a un determinat municipi pot no ser la mateixa en peticions on els àmbits territorials seleccionats són diferents.

L'operació dades ha d'incloure obligatòriament el paràmetre id o bé el paràmetre i. Si no s'inclou cap dels dos, no es retornaran dades de cap indicador.

1.2.1.3. Filtre `tipus`

El paràmetre tipus pot utilitzar-se en peticions sense paràmetre id per limitar els àmbits inclosos en la resposta d'acord amb la tipologia següent:

cat: Catalunya
com: Comarques
mun: Municipis

Aquests valors es poden concatenar separats per comes. Per defecte, tipus és igual a cat,com,mun.

1.2.2. Operació `nodes`

L'operació nodes retorna els àmbits territorials previstos en el servei i permet conèixer els valors vàlids del paràmetre id de l'operació dades.

Ex. 4: Llista jeràrquica d'àmbits territorials (Catalunya, comarques, municipis) i els seus codis en format JSON

https://api.idescat.cat/emex/v1/nodes.json

1.2.2.1. Filtre `tipus`

El paràmetre tipus en l'operació nodes té el mateix significat i accepta els mateixos valors que en l'operació dades.

Ex. 5: Llista de comarques de Catalunya i els seus codis en format JSON

https://api.idescat.cat/emex/v1/nodes.json?tipus=com

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

Llista de tots els àmbits territorials disponibles en format XML
```
https://api.idescat.cat/emex/v1/geo.xml
```
Llista de les comarques de Catalunya en format XML
```
https://api.idescat.cat/emex/v1/geo.xml?tipus=com
```
Informació de l'indicador f171 (població) de Catalunya i les seves comarques en format JSON
```
https://api.idescat.cat/emex/v1/geo.json?i=f171&tipus=cat,com
```
Informació completa de l'àmbit territorial 01 (Alt Camp) en format XML
```
https://api.idescat.cat/emex/v1/geo/01.xml
```
Informació completa de l'àmbit territorial 170010 (Agullana) en format JSON
```
https://api.idescat.cat/emex/v1/geo/170010.json
```
Informació dels indicadors f328 (longitud) i f329 (latitud) de l'àmbit territorial 170010 (Agullana) en format PHP serialitzat
```
https://api.idescat.cat/emex/v1/geo/170010.php?i=f328,f329
```

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. L'element arrel (`fitxes`)

L'element arrel (fitxes) apareix en totes les respostes, sigui quina sigui l'operació. Inclou els atributs següents:

version: versió del servei.
lang: idioma general del document. Aquest servei admet el valor oc, a més de ca (valor per defecte), es i en.
o: operació sol·licitada.
p: valors assignats als paràmetres específics, si n'hi ha.

Ex. 6: Atributs de l'element arrel en una operació `dades`

<fitxes
   version="1.00"
   lang="ca"
   o="dades"
   p="id=080155"
>

2.2. Operació `dades`

L'estructura de la resposta de l'operació dades depèn de si s'ha especificat una llista d'indicadors (i) o no. En tots dos casos, la resposta conté l'element cols.

2.2.1. Columnes (`cols`)

L'element cols conté informació dels àmbits territorials per als quals s'inclou informació estadística. Per a cada àmbit, aquest element conté un element col amb un codi (valor de l'atribut id) i una denominació (contingut de l'element). El nivell territorial s'especifica a l'atribut scheme: municipi (mun), comarca (com) o Catalunya (ca).

Ex. 7: Element `cols` en una operació `dades`

<cols>
   <col id="080155" scheme="mun">Badalona</col>
   <col id="13" scheme="com">Barcelonès</col>
   <col id="09" scheme="ca">Catalunya</col>
</cols>

2.2.2. Resposta amb tots els indicadors

2.2.2.1. Grups (`g`), taules (`t`), files (`f`), denominacions (`c`) i vectors de valors (`v`)

Quan se sol·liciten tots els indicadors disponibles per a un àmbit determinat, aquests s'inclouen en un element gg (conjunt de grups). Dins d'aquest element, la informació es presenta agrupada en diferents nivells: grups, taules i files.

Cada grup (g) disposa d'un identificador (atribut id), d'una denominació (c) i, o bé d'un conjunt de taules (tt) o bé d'un nou conjunt de grups (gg). Aquesta segona possibilitat no s'utilitza actualment a l'API del municipi en xifres. Cada taula (t) disposa d'un identificador (atribut id), d'una denominació (c) i d'un conjunt de files (o indicadors) (ff). I cada fila (f) disposa d'un identificador (atribut id), d'una denominació (c) i d'un vector de valors (v).

El vector de valors (v) conté tantes xifres separades per comes com columnes (col). Els decimals s'indiquen amb punt i els valors que falten amb "_".

Ex. 8: Un grup `g` i els seus nivells inferiors

<g id="g158">
    <c>Moviment de la població</c>
    <tt>
        <t id="t164">
            <c>Naixements. Per sexe</c>
            <ff>
                <f id="f185">
                    <c>Nens</c>
                    <v>1386,12043,45984</v>
                    ...
                </f>
                <f id="f186">
                    <c>Nenes</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. Denominació alternativa (`calt`)

Els noms (c) de taules (t) i files (f) poden tenir una denominació alternativa (calt). En el cas de les taules, calt ofereix una denominació, en general més breu que c, apropiada per a una llista de continguts del grup. Pel que fa a les files, com c ja ofereix una denominació que només és comprensible en el context d'una taula, calt proporciona una denominació breu útil per presentar les files per separat (com a indicadors), en comptes d'agrupades en una taula.

Ex. 9: L'element `calt` de taules (`t`) i files (`f`)

<t id="t164">
    <c>Naixements. Per sexe</c>
    <calt>Naixements</calt>
    <ff>
        <f id="f185">
            <c>Nens</c>
            <calt>Naixements de nens</calt>
            <v>1386,12043,45984</v>
        </f>
        <f id="f186">
            <c>Nenes</c>
            <calt>Naixements de nenes</calt>
            <v>1348,11160,43040</v>
        </f>
        <f id="f187">
            <c>Total</c>
            <calt>Naixements</calt>
            <v>2734,23203,89024</v>
        </f>
    </ff>
    ...
</t>

2.2.2.3. Unitats (`u`), referència temporal (`r`) i data d'actualització (`updated`)

El vector de valors (v) de cada fila (f) de la taula (t) està expressat en unitats (u), es refereix a un període temporal (r) i té una data d'actualització (updated).

Habitualment, les files d'una taula comparteixen el contingut de tots o alguns d'aquests elements. En aquests casos, l'API retorna l'element com a fill de la taula (t) en comptes d'aparèixer repetit a cada fila (f).

El contingut d'u proporciona un literal expressiu de les unitats de mesura que complementa la denominació de la taula o la fila. Quan aquesta unitat resulta òbvia en la mateixa denominació (p.e. "Naixements"), l'element u no apareix.

Ex. 10: Fila (`f`) amb unitats (`u`)

<f id="f3">
    <c>PIB pm per habitant</c>
    <calt>PIB per habitant</calt>
    <v>18.1,30.7,27.3</v>
    <u>Milers d'euros</u>
</f>

Totes les dades d'aquest servei tenen una referència temporal anual que apareix expressada en quatre dígits com a contingut de l'element r. Aquest element sempre apareix, ja sigui com a fill d'f o com a fill de t.

Totes les dades d'aquest servei tenen una data d'actualització que apareix com a contingut de l'element updated. Aquest element sempre apareix, ja sigui com a fill de f o com a fill de t. El format de data emprat es pot veure en l'exemple següent (vegeu l'RFC3339 per a la seva interpretació).

Ex. 11: Elements `r` i `upated` comuns a totes les files `f` d'una taula `t`

<g id="g158">
    <c>Moviment de la població</c>
    <tt>
        <t id="t164">
            <c>Naixements. Per sexe</c>
            <calt>Naixements</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. Font (`s`) i enllaç (`l`)

Totes les taules tenen associat un text descriptiu de la font de la informació (s) així com un possible enllaç amb la taula d'on s'ha extret (l), si existeix.

Ex. 12: Elements `r` i `upated` comuns a totes les files `f` d'una taula `t`

<t id="t176">
    <c>Indicadors geogràfics</c>
    <ff>
        <f id="f258">
            <c>Altitud</c>
            <calt>Altitud</calt>
            <v>105,_,_</v>
            <u>m</u>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </f>
        <f id="f259">
            <c>Coordenades UTM x</c>
            <calt>Coordenades UTM x</calt>
            <v>408471,_,_</v>
            <u>m</u>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </f>
        <f id="f260">
            <c>Coordenades UTM y</c>
            <calt>Coordenades UTM y</calt>
            <v>4596983,_,_</v>
            <u>m</u>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </f>
    </ff>
    <r>2009</r>
    <s>Idescat, a partir de les dades de l'Institut Cartogràfic de Catalunya.</s>
    <l>
          https://www.idescat.cat/pub/?id=inddt&amp;n=396&amp;geo=muni080018
    </l>
</t>

2.2.3. Resposta amb una selecció d'indicadors

L'API permet seleccionar els indicadors que cal incloure a la resposta amb el paràmetre i. En aquest cas, enlloc de l'element gg, apareix l'element indicadors.

Aquest element inclou la informació dels indicadors seleccionats seguint una estructura basada en l'API d'Indicadors al dia on l'element dc:date ha estat substituït per updated i v és un vector en comptes d'un valor únic. Com a denominació de l'indicador (c) apareix el que, en les peticions on no s'ha especificat i, és el contingut de calt de la fila (f). Finalment, t inclou l'identificador i la denominació de la taula a la qual pertany l'indicador.

Ex. 13: Sortida de l'operació `dades` d'una petició de dos indicadors, un d'incorrecte ("156") i l'altre correcte ("f2"), per a Abrera

<?xml version="1.0" encoding="utf-8"?>
<fitxes version="1.00" lang="ca" 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">Catalunya</col>
    </cols>
    <indicadors>
        <i id="156" error="404">
            <c>Indicador no trobat</c>
        </i>
        <i id="f2">
            <c>PIB pm</c>
            <v>608.5,21576.4,195857.8</v>
            <u>Milions d'euros</u>
            <r>2006</r>
            <s>Idescat.</s>
            <t id="t1">Producte interior brut a preus de mercat (base 2000)</t>
            <l>
                 https://www.idescat.cat/pub/?id=pibc&amp;n=8276&amp;geo=muni080018
            </l>
            <updated>2010-06-11T10:00:00+00:00</updated>
        </i>
    </indicadors>
</fitxes>

Ex. 14: Sortida de l'operació `dades` d'un indicador ("f187"), per comarques

<?xml version="1.0" encoding="utf-8"?>
<fitxes version="1.00" lang="ca" 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>Naixements</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. Moviment natural de la població.</s>
            <t id="t164">Naixements. Per sexe</t>
            <updated>2011-10-13T10:00:00+00:00</updated>
        </i>
    </indicadors>
</fitxes>

2.3. Operació `nodes`

Els municipis s'agrupen en comarques i aquestes s'agrupen sota l'àmbit territorial de Catalunya. Aquesta jerarquia s'expressa en un seguit d'elements v imbricats. Cadascun d'aquests elements disposa d'un atribut id amb el codi de l'àmbit territorial i d'un atribut scheme amb especificació del nivell territorial: municipi ("mun"), comarca ("com") o Catalunya ("ca").

<?xml version="1.0" encoding="utf-8"?>
<fitxes version="1.00" lang="ca" 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

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

El municipi en xifres. API

1. Petició

1.1. Característiques bàsiques

1.1.1. Identificador del servei i versió

1.1.2. Operacions

1.2. Paràmetres específics

1.2.1. Operació dades

1.2.1.1. Filtre id

Ex. 1: Informació estadística bàsica d'Abella de la Conca (250019), el Pallars Jussà i Catalunya

1.2.1.2. Filtre i

Ex. 2: Dades de població total, masculina i femenina d'Abrera, el Baix Llobregat i Catalunya

Ex. 3: Dades de població total, masculina i femenina de tots els municipis, comarques i Catalunya

1.2.1.3. Filtre tipus

1.2.2. Operació nodes

Ex. 4: Llista jeràrquica d'àmbits territorials (Catalunya, comarques, municipis) i els seus codis en format JSON

1.2.2.1. Filtre tipus

Ex. 5: Llista de comarques de Catalunya i els seus codis en format JSON

1.3. Invocació sense operació

2. Resposta

2.1. L'element arrel (fitxes)

Ex. 6: Atributs de l'element arrel en una operació dades

2.2. Operació dades

2.2.1. Columnes (cols)

Ex. 7: Element cols en una operació dades

2.2.2. Resposta amb tots els indicadors

2.2.2.1. Grups (g), taules (t), files (f), denominacions (c) i vectors de valors (v)

Ex. 8: Un grup g i els seus nivells inferiors

2.2.2.2. Denominació alternativa (calt)

Ex. 9: L'element calt de taules (t) i files (f)

2.2.2.3. Unitats (u), referència temporal (r) i data d'actualització (updated)

Ex. 10: Fila (f) amb unitats (u)

Ex. 11: Elements r i upated comuns a totes les files f d'una taula t

2.2.2.4. Font (s) i enllaç (l)

Ex. 12: Elements r i upated comuns a totes les files f d'una taula t