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.
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ó
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&n=396&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&n=8276&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.