API de Dades Obertes

Què fa l’API?

Una API o interfície de programació d’aplicacions és un conjunt de mètodes que recuperen dades perquè puguin ser processades per altres aplicacions.

Un cop es coneix l’estructura de les dades, només cal cridar els mètodes corresponents, tenint en compte que es poden combinar els mètodes entre si.

 

Estructura de les dades

A nivell general utilitzem els següents conceptes:

  • Tipus de contingut: Definim un tipus de contingut concret a partir d'un nombre arbitrari de camps, grups i relacions. Exemple: El tipus de contingut “recinte”, tindria tots els camps relatius a un recinte (nom, adreça, m2, etc.).
  • Dataset: Definim un dataset com un conjunt de dades d'un tipus de contingut concret; per exemple, l'agenda d'actes de les biblioteques. Un dataset és un subconjunt del tipus de contingut. Exemple: el dataset “recintes” té dades del tipus de contingut “recinte”.
  • Relació: Les relacions ens permeten connectar dades d'un tipus de contingut amb un dataset concret o un altre tipus de contingut. Per exemple, podem definir un dataset que sigui la llista de municipis i un tipus de contingut per a actes, podent relacionar totes dues dades a partir d'un identificador únic (codi INE). La gràcia de tenir les dades relacionades és que en recuperar la informació, també és possible recuperar les dades relacionades. Exemple: El tipus de contingut “recinte” podria estar relacionat amb el tipus de contingut “municipi”; llavors, quan recuperéssim un recinte, també recuperaria informació del municipi on està ubicat.
  • Grup: Un grup no és res més que un conjunt o agrupació de camps.
  • Camp: Els camps defineixen els diferents valors que pot tenir un tipus de contingut.

 

Mètodes

L'API només és de consulta, via REST i utilitza URLs “netes” per a les crides. Per tant, no hi ha paràmetres GET, sinó que en el seu lloc utilitza un sistema de parelles de paràmetre i valor.

La ruta és: http://do.diba.cat/api/_CRIDA_

_CRIDA_ : parametre1/valor1/parametre2/valor2/parametreN/valorN

 

Totes les dades són accessibles en format CSV, XML i JSON (per defecte, retorna els resultats en JSON). Els formats amb XML i JSON contindran l'estructura interna de camps i grups que s'ha definit; en canvi, el format CSV per la seva naturalesa només permet els valors dels camps de forma lineal sense estructura. Per als camps multiavaluats en format CSV, s'utilitza un caràcter separador “;” per separar els diferents valors dins d'un mateix camp: “valor1_camp1”,”valor1_camp2;valor2_camp2;valor3_camp2”,”valor1_camp3”...

No importa l'ordre en què es cridin els parells. Si els paràmetres tenen un valor per defecte i no incloem a la ruta el valor d’un paràmetre que és obligatori, aquest prendrà el valor per defecte.

Un concepte clau que està definit en tots els tipus de continguts, datasets i camps és el machinename o nom-màquina. Es tracta d’un valor preparat especialment perquè l’utilitzi el software i les màquines, que no canvia mai i que no conté cap caràcter especial, ni espais en blanc i es limita al subconjunt de caràcters ASCII-96. Aquest valor s’utilitza com a identificador i és ideal per utilitzar en totes les crides independentment del joc de caràcters utilitzat, perquè el subconjunt ASCII-96 és comú en tots els jocs de caràcters; per tant, sempre que sigui possible s’ha de treballar amb el machinename.

 

Els mètodes disponibles són els següents:

  • Recuperació de l’estructura (tipus de contingut)
  • Informació del dataset i darrers canvis
  • Selecció de datasets
  • Selecció de l’idioma (operador IDIOMA)
  • Selecció de tipus de contingut
  • Valor d'un camp
  • Operador LIKE
  • Operador LOWER i LOWEREQUAL
  • Operador GREATER i GREATEREQUAL
  • Operador ORNULL
  • Operador OR i AND
  • Operador AGREGA
  • Cerca a tots els camps (operador CAMP-ALL, CAMP-ALL-LIKE)
  • Paginació
  • Ordenació
  • Ordenació i filtre per proximitat
  • Geolocalització i proximitat
  • Format de sortida

Els exemples del retorn de la informació que mostrem a cada mètode són orientatius i el seu objectiu és servir d’explicació.

 

Recuperació de l’estructura i les descripcions

Recuperació de l’estructura (tipus de contingut)

Permet recuperar la llista de tipus de continguts i amb la seva relació de camps.

  • Paràmetre: info
  • Valor: tipus

Exemple: http://do.diba.cat/api/info/tipus tornarà les estructures i informació de tots els tipus de contingut definits amb els seus camps, grups i relacions. També podem restringir i aquesta llista i recuperar un sol tipus de contingut combinant filtres, per exemple: http://do.diba.cat/api/info/tipus/tipus/acte recuperarà l’estructura i informació del tipus de contingut “acte”.

El retorn seria una informació com aquesta:

<tipus>
            <element>
                        <nom>Acte</nom>
                        <machinename>actes</machinename>
                        <descripcio>Agenda d'actes</descripcio>
                        <entitats>2346</entitats>
                        <camps>
                                   <camp>
                                               <nom>Títol</nom>
                                               <machinename>titol</machinename>
                                               <pes>1</pes>
                                               <primari>0</primari>
                                               <repetible>0</repetible>
                                               ...etc...
                                   </camp>
                                   ...etc...
                        </camps>
            </element>
</tipus>

 

Informació del dataset i darrers canvis

Podem recuperar la descripció d’un dataset i la darrera data de modificació d’alguna de els seves dades:

  • Paràmetre: info
  • Valor: dataset

Exemple: http://do.diba.cat/api/info/datasets per recuperar les descripcions de tots els datasets visibles, o http://do.diba.cat/api/info/datasets/dataset/biblioteques per recuperar la informació específica d’un sol data set.

La sortida tindrà la forma següent:

<nom>Xarxa de Biblioteques</nom>
<machinename>biblioteques</machinename>
<descripcio>Xarxa de Biblioteques Municipals de la província de Barcelona.</descripcio>
<tipus>punt</tipus>
<estat>public</estat>
<creacio>2013-09-19</creacio>
<modificacio>2015-04-01</modificacio>
<entitats>226</entitats>
<camps>
            <camp>
                        <nom>Títol</nom>
                        <machinename>titol</machinename>
                        <pes>1</pes>
                        <primari>0</primari>
                        <repetible>0</repetible>
                        ...etc...
            </camp>
            ...etc...
</camps>

 

Recuperació de les dades

Tots els datasets incorporen dos camps especials que poden ser utilitzar com un paràmetre més en totes els crides per filtrar o ordenar. Es tracta dels camps:

  • _id: Identificador únic intern universal.
  • _lastChange: Dada de la darrera modificació o creació del registre.

Al no tractar-se d’una dada específica de la font original de les dades comencen pel caràcter “_”

 

Selecció de datasets

Permet recuperar qualsevol conjunt de dades (dataset) especificant el nom-màquina (machinename) del conjunt de dades (tot i que pot ser el mateix, no s’ha de confondre amb el nom del dataset).

  • Paràmetre: dataset
  • Valor: nom-màquina

Exemple: http://do.diba.cat/api/dataset/municipis tornarà els municipis.

El retorn seria una cosa així:

<dataset>
            <nom>Municipis</nom>
            <machinename>municipis</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <tipus>municipi</tipus>
            <estat>públic</estat>
            <creació>11/11/2012 11:23</creació>
            <modificació>12/11/2012 09:26</modificació>
            <entitats>311</entitats>
            <elements>
                        <element>
                                   <camp1>valor1</camp1>
                                   <camp2>valor2</camp2>
                                   <camp3>valor3</camp3>
                                   etc...
                        </element>
                        <element>
                                   <camp1>valor1</camp1>
                                   <camp2>valor2</camp2>
                                   <camp3>valor3</camp3>
                                    etc...
                        </element>
            </elements>
</dataset>

 

Selecció de l’idioma

Hi ha vàries maneres de recuperar la informació d’un idioma concret d’un dataset:

El retorn seria una cosa així:

<dataset>
            <nom>Equipaments de Parcs</nom>
            <machinename>parcsequipaments_ca</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>664</entitats>
            <elements>
                        <element>
                                   <camp1>valor1</camp1>
                                   <camp2>valor2</camp2>
                                   <camp3>valor3</camp3>
                                   etc...
                        </element>
                        <element>
                                   <camp1>valor1</camp1>
                                   <camp2>valor2</camp2>
                                   <camp3>valor3</camp3>
                                    etc...
                        </element>
            </elements>
</dataset>

 

Selecció de tipus de contingut

Permet recuperar totes les dades d'un tipus de contingut concret especificant el nom-màquina (machinename) del tipus de contingut.

  • Paràmetre: tipus
  • Valor: nom-màquina

Exemple: http://do.diba.cat/api/tipus/municipi tornarà els continguts de tipus agenda

<tipus>
            <nom>Municipis</nom>
            <machinename>municipi</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <entitats>311</entitats>
            <datasets>
                        <dataset>
                        <nom>Municipis</nom>
                        <machinename>municipis</machinename>
                        <descripcio>Bla, bla, bla...</descripcio>
                        <tipus>agenda</tipus>
                        <estat>públic</estat>
                        <creació>11/11/2012 11:23</creació>
                        <modificació>12/11/2012 09:26</modificació>
                        <entitats>311</entitats>
                                <elements>
                                               <element>
                                                           <camp1>valor1</camp1>
                                                           <camp2>valor2</camp2>
                                                           <camp3>valor3</camp3>
                                                           etc...
                                               </element>
                                               <element>
                                                           <camp1>valor1</camp1>
                                                           <camp2>valor2</camp2>
                                                           <camp3>valor3</camp3>
                                                           etc...
                                               </element>
                                 </elements>
                                 etc...
                        </dataset>
                        etc...
            </datasets>
</tipus>

 

Valor d'un camp

Permet recuperar totes les dades que tinguin un valor concret d'un camp. En el paràmetre s’afegeix un guió i el machinename del camp.

  • Paràmetre: camp-machinename
  • Valor: valor

Important: Aquest filtre no funciona aïllat, és necessari especificar tipus/tipus_contingut o dataset/nom_dataset.

Important per camps tipus “data”:

En el cas que el camp sigui data, hi ha dos possibles formats:

  • Aaaa-mm-dd: aquest es crida afegint com a prefix del valor cercat, la paraula “date:” i accepta dos possibles valors, “date:aaaa-mm-dd” o “date:now”
  • Aaaa-mm-dd_hh:mm:ss: aquest es crida afegint com a prefix del valor cercat, la paraula “datetime:” i accepta dos possibles valors, “datetime:aaaa-mm-dd_hh:mm:ss” o “datetime:now”

Exemple: http://do.diba.cat/api/tipus/bibliobus/camp-nom/Bibliobús Montnegre ens tornarà totes les dades que tinguin el camp nom exactament igual a “Bibliobús Montnegre”.

<tipus>
            <nom>Bibliobús</nom>
            <machinename>bibliobus</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <entitats>234224</entitats>
            <datasets>
                      <dataset>
                      <nom>Bibliobusos</nom>
                      <machinename>bibliobusos</machinename>
                      <descripcio>Bla, bla, bla...</descripcio>
                      <tipus>bibliobus</tipus>
                      <estat>públic</estat>
                      <creació>11/11/2012 11:23</creació>
                      <modificació>12/11/2012 09:26</modificació>
                      <nombre>1</nombre>
                                 <elements>
                                               <element>
                                                           <camp1>Bibliobús Montnegre</camp1>
                                                           <camp2>valor2</camp2>
                                                           <camp3>valor3</camp3>
                                                           etc...
                                               </element>
                                 </elements>
                                 etc...
                      </dataset>
                      etc...
            </datasets>
</tipus>

 

Operador LIKE

Es permet fer servir l'operador LIKE en comptes de la cerca exacta quan es demanen valors concrets d'un camp. En aquest cas cal afegir en el paràmetre un guió i la paraula “like” després del machinename.

  • Paràmetre: camp-machinename-like
  • Valor: valor

Exemple: http://do.diba.cat/api/tipus/bibliobus/camp-nom-like/Montnegre/format/xml tornarà totes les dades que continguin “Montnegre” en el nom.

<tipus>
            <nom>Bibliobús</nom>
            <machinename>bibliobus</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <entitats>234224</entitats>
            <datasets>
                        <dataset>
                        <nom>Bibliobusos</nom>
                        <machinename>bibliobusos</machinename>
                        <descripcio>Bla, bla, bla...</descripcio>
                        <tipus>bibliobus</tipus>
                        <estat>públic</estat>
                        <creació>11/11/2012 11:23</creació>
                        <modificació>12/11/2012 09:26</modificació>
                        <nombre>1</nombre>
                                 <elements>
                                             <element>
                                                         <camp1>Bibliobús Montnegre</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                 </elements>
                                 etc...
                      </dataset>
                      etc...
            </datasets>
</tipus>

 

Operador LOWER i LOWEREQUAL

Es permet utilitzar l'operador LOWER (menor) o LOWEREQUAL (menor o igual) en els camps de tipus numèric i de data. Cal afegir en el paràmetre un guió i la paraula “lower” després del machinename.

  • Paràmetre: camp-machinename-lower
  • Valor: valor

Exemple: http://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-data_inici-lower/datetime:2016-04-10_09:00:00 tornarà totes les dades amb el camp data_inici menor al 10/04/2016 a les 9:00:00.

<tipus>
            <nom> Agenda de les Biblioteques en català</nom>
            <machinename> actesbiblioteques_ca</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>89</entitats>
            <datasets>
                        <dataset>
                                   <element>
                                               <data_inici> 2016-02-08 10:00:00</data_inici>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                        </dataset>
                        etc...
            </datasets>
</tipus>

 

Operador GREATER i GREATEREQUAL

Es permet utilitzar l'operador GREATER (major) o GREATEREQUAL (major o igual) en els camps de tipus numèric i de data. Cal afegir en el paràmetre un guió i la paraula “greater” després del machinename.

  • Paràmetre: camp-machinename-greater
  • Valor: valor

Exemple: http://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-data_inici-greater/datetime:2016-04-10_09:00:00 tornarà totes les dades amb el camp data major al 10/04/2016 a les 9:00:00.

<tipus>
            <nom> Agenda de les Biblioteques en català</nom>
            <machinename>actesbiblioteques_ca</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>1192</entitats>
            <datasets>
                        <dataset>
                                   <element>
                                               <data_inici> 2016-04-11 18:30:00</data_inici>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                        </dataset>
                        etc...
            </datasets>
</tipus>

 

Operador ORNULL

Es permet afegir l'operador ORNULL quan es demanen valors concrets d'un camp però que poden ser NULL. En aquest cas cal afegir en el paràmetre un guió i la paraula “ornull” després del machinename.

  • Paràmetre: camp-machinename-ornull
  • Valor: valor

Exemple: http://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-preu-ornull/10 tornarà totes les dades que continguin “10” en el preu o null.

<tipus>
            <nom>Agenda de les Biblioteques en català</nom>
            <machinename>actesbiblioteques_ca</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>1192</entitats>
            <datasets>
                        <dataset>
                                   <element>
                                               <preu></preu>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                                   <element>
                                               <preu>10</preu>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                                   ...etc...
                        </dataset>
                        etc...
            </datasets>
</tipus>

 

Operador AND i OR

Es permet afegir l'operador AND i OR sobre els valors d’un camp. L’operador AND només té sentit si el camp és multivalent (que pot tenir més d’un valor) i es materialitza amb “++” i el OR amb “||”.

  • Paràmetre: camp-machinename
  • Valor: valor++valor++valor
    • Valor||valor||valor

Exemple: http://do.diba.cat/api/camp-dies/Dimarts||Dijous tornarà totes les dades dels dies “Dimarts” o “Dijous”.

<tipus>
            <nom>Agenda de les Biblioteques en català</nom>
            <machinename>actesbiblioteques_ca</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>107</entitats>
            <datasets>
                        <dataset>
                                   <element>
                                               <dies>Dimarts</dies>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                                   <element>
                                               <dies>Dijous</dijous>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                                   ...etc...
                        </dataset>
                        etc...
            </datasets>
</tipus>

Exemple: http://do.diba.cat/api/camp-categoria/intercanvi_linguistic++adults tornarà totes les dades dels actes amb categoria “intercanvi_linguistic” i “adults”, entre altres.

<tipus>
            <nom>Agenda de les Biblioteques en català</nom>
            <machinename>actesbiblioteques_ca</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>107</entitats>
            <datasets>
                        <dataset>
                                   <element>
                                               <categoria>intercanvi_linguistic, adults </categoria>
                                               <camp2>valor2</camp2>
                                               <camp3>valor3</camp3>
                                               etc...
                                   </element>
                                   ...etc...
                        </dataset>
                        etc...
            </datasets>
</tipus>

 

Operador AGREGA

Es permet afegir l'operador AGREGA per un o múltiples camps. La resta de filtres són aplicables (filtres, formats o paginació).

  • Paràmetre: agrega/machinename/agrega/machinename/...etc...

Exemple, recompte de càrrecs electes per sexe i municipi (codi INE): do.diba.cat/api/dataset/electes/agrega/codi_ine/agrega/sexe

<tipus>
            <nom> Electes</nom>
            <machinename>electes</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>3764</entitats>
            <grupEntitats>3</grupEntitats>
            <elements>
                        <element>
                                   <data.codi_ine>null</dies>
                                   <data.sexe>D</data.sexe>
                                   <count>1375</count>
                        </element>
                        <element>
                                   <data.codi_ine>null</dies>
                                   <data.sexe>H</data.sexe>
                                   <count>2290</count>
                        </element>
                        <element>
                                   <data.codi_ine>null</dies>
                                   <data.sexe></data.sexe>
                                   <count>99</count>
                        </element>
            </elements>
</tipus>

 

Cerca a tots els camps

Es permet cercar per text lliure en tots els camps alhora. Es pot cercar per text concret o amb operador LIKE.

  • Paràmetre: camp-all/text
    • camp-all-like/text

Exemple: cercar a les biblioteques, qualsevol camp que sigui “berga” . http://do.diba.cat/api/dataset/biblioteques/camp-all-like/berga

<tipus>
            <nom> Xarxa de Biblioteques </nom>
            <machinename> biblioteques </machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            ...etc...
            <entitats>2</entitats>
            <elements>
                        <element>
                                   <punt_id>biblioteca423596</punt_id>
                                   <adreca> Carretera de Berga, grup c s/n 08580 Sant Quirze de Besora </adreca>
                                   ...etc...
                        </element>
             ...etc...
            </elements>
</tipus>

 

Paginació

Per motius de rendiment per defecte qualsevol consulta torna els 1000 primers resultats. Si es volen recuperar més resultats o els següents, cal indicar-ho amb els paràmetres “pag-ini” (inici de la paginació) i “pag-fi” (final de la paginació).

  • Paràmetres: pag-ini / pag-fi
  • Valors: Numèric. Element d'inici i de fi de la paginació.

Exemple: pag-ini/1/pag-fi/10 ens tornarà els 10 primers elements pag-ini/11/pag-fi/20 ens tornarà els 10 elements següents.

 

Ordenació

Per defecte els resultats no s'ordenen i es tornen tal com surten de la base de dades sense cap criteri concret. Si es volen ordenar, es pot indicar el camp que s'utilitza per a l’ordenació amb el paràmetre “ord-camp” i el sentit d'ordenació amb “ord-sentit”. Per defecte el sentit serà sempre “asc” (ascendent).

  • Paràmetres: ord-nommachine_camp/ord-sentit
  • Valors: no té valor, va implícit en el paràmetre / no té valor, va implícit en el paràmetre

Exemple: http://do.diba.cat/api/tipus/municipi/ord-municipi_nom/desc ordenarà els resultats de forma descendent.

<tipus>
            <element>Municipis</element>
            <machinename>municipis</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <tipus>municipis</tipus>
            <estat>públic</estat>
            <creació>11/11/2012 11:23</creació>
            <modificació>12/11/2012 09:26</modificació>
            <nombre>311</nombre>
                                 <elements>
                                             <element>
                                                         <camp1>Òrrius</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                             <element>
                                                         <camp1>Òdena</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                 </elements>
                                 etc...
                      </dataset>
                      etc...
          </datasets>
</tipus>

 

Ordenació i filtre per proximitat

Es pot filtrar i ordenar per proximitat a una coordenada. En aquest cas, cal indicar la teva geolocalització al camp de coordenades que utilitzes per a la comparació.

  • Paràmetres: geord-camp / geord-cord
  • Valors: machinename / coordenades

Exemple: http://do.diba.cat/api/geord-camp/localitzacio/geord-cord/41.34220,2.2678 ens ordenarà els resultats per proximitat al voltant de les coordenades 41.342 -2.2678 i el valor del camp

“localitzacio”.

<tipus>
            <element>Municipis</element>
            <machinename>municipis</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <tipus>municipis</tipus>
            <estat>públic</estat>
            <creació>11/11/2012 11:23</creació>
            <modificació>12/11/2012 09:26</modificació>
            <nombre>234224</nombre>
                                 <elements>
                                             <element>
                                                         <camp1>41.5160212,1.901287</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                             <element>
                                                         <camp1>41.1173956,1.2543555</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                 </elements>
                                 etc...
                      </dataset>
                      etc...
          </datasets>
</tipus>

 

Geolocalització i proximitat

Es pot filtrar per proximitat a una coordenada. En aquest cas, cal indicar la teva geolocalització, el camp de

coordenades que s’utilitza per a la comparació i el radi de proximitat en metres.

  • Paràmetres: ubicacio / geocamp / radi
  • Valors: coordenada / machinename / integer (metres)

Exemple: http://do.diba.cat/api/dataset/municipis/ubicacio/41.5606948,1.523511/geocamp/localitzacio/radi/2000 ens tornarà totes les dades que, segons la coordenada que indica el camp “localitzacio”, estiguin a menys de 2000m de la coordenada 41.5606948,1.523511.

<tipus>
            <nom>Municipis</nom>
            <machinename>municipis</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <entitats>1</entitats>
            <datasets>
                        <element>
                                   <localitzacio>41.5606948,1.523511</localitzacio>
                                   <camp2>valor2</camp2>
                                   <camp3>valor3</camp3>
                                   etc...
                        </element>
            </datasets>
</tipus>

 

Ordenació per proximitat

Un cas especial d'ordenació és l’ordenació dels resultats per proximitat. En aquest cas, cal indicar la teva geolocalització al camp de coordenades que utilitzes per a la comparació.

  • Paràmetres: geord-camp / geord-cord
  • Valors: machinename / coordenades

Exemple: http://do.diba.cat/api/geord-camp/localitzacio/geord-cord/41.34220,2.2678 ens ordenarà els resultats per proximitat al voltant de les coordenades 41.342 -2.2678 i el valor del camp “localitzacio”.

<tipus>
            <element>Municipis</element>
            <machinename>municipis</machinename>
            <descripcio>Bla, bla, bla...</descripcio>
            <tipus>municipis</tipus>
            <estat>públic</estat>
            <creació>11/11/2012 11:23</creació>
            <modificació>12/11/2012 09:26</modificació>
            <nombre>311</nombre>
                                 <elements>
                                             <element>
                                                         <camp1> Sant Martí de Tous</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                             <element>
                                                         <camp1> Jorba</camp1>
                                                         <camp2>valor2</camp2>
                                                         <camp3>valor3</camp3>
                                                         etc...
                                             </element>
                                 </elements>
                                 etc...
                      </dataset>
                      etc...
          </datasets>
</tipus>

 

Format de sortida

Per defecte la sortida és amb format JSON, però es pot demanar la sortida en un altre format, en primera fase XML i CSV.

  • Paràmetre: format
  • Valors: json2, json o xml o csv

Exemple: format/xml tornarà les dades en XML en lloc de JSON.

El format per defecte format/json està deprecat i es recomana utilitzar format/json2 que te una estructura simplificada i es molt més eficient.

 

Combinatòria de criteris

Finalment, cal tenir en compte que els criteris i paràmetres són combinables entre ells, tot i que s’ha d’entendre que la combinació pot no retornar resultats.

Exemple: http://do.diba.cat/api/dataset/municipis/geord-camp/localitzacio/geord-cord/41.5606948,1.523511/pag-ini/1/pag-fi/10

Aquesta crida ens tornarà les dades del municipis i ens tornarà els primers 10 resultats ordenats per proximitat a la coordenada 41.5606948,1.523511 que s’ha indicat.

Exemples reals

Llista dels conjunts de dades disponibles:
http://do.diba.cat/api/info/datasets

Llista dels tipus de continguts disponibles:
http://do.diba.cat/api/info/tipus

Llista de temes o àmbits temàtics d'actuació de la Diputació de Barcelona:
http://do.diba.cat/api/dataset/temes

Llista de municipis de la província de Barcelona:
http://do.diba.cat/api/dataset/municipis

Llista dels municipis de la província de Barcelona en format XML:
http://do.diba.cat/api/dataset/municipis/format/xml

Llista d'actes de la cartellera dels espais escènics municipals:
http://do.diba.cat/api/dataset/escenari

Tots els punts d'interès de qualsevol conjunt de dades:
http://do.diba.cat/api/tipus/punt

Tots els actes de qualsevol conjunt de dades:
http://do.diba.cat/api/tipus/acte

Els 10 punts d'interès més propers a Santa Coloma de Gramenet (41.453889,2.211111):
 http://do.diba.cat/api/tipus/punt/geord-camp/localitzacio/geord-cord/41.453889,2.211111/pag-ini/1/pag-fi/10

Les dades de l'acte amb identificador = escenari286630595286564:
http://do.diba.cat/api/dataset/escenari/camp-acte_id/escenari286630595286564

Registres modificats avui en el dataset de biblioteques:
http://do.diba.cat/api/dataset/biblioteques/camp-_lastChange/date:now

Registres modificats amb data igual o superior a l’1 de febrer de 2015 a les 15:00h en el dataset municipis:
http://do.diba.cat/api/dataset/biblioteques/camp-_lastChange-greaterequal/datetime:2015-02-01_15:00:00

Biblioteques a 1000 metres de distància de la coordenada 41.37,2.18:
http://do.diba.cat/api/dataset/biblioteques/format/json2/ubicacio/41.37,2.18/geocamp/localitzacio/radi/1000