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.

Pots navegar pels diferents apartats de la documentació tècnica de l'API REST de dades obertes, utilitzar el nostre cercador de documentació o descarregar-te la versió completa per imprimir.

 

Cercador de documentació Versió per imprimir

Taula de continguts

Què és l'API REST?

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

REST és una arquitectura de software per a sistemes hipermedia. Actualment REST és el terme que s'utilitza per descriure tota interfície entre sistemes que utilitzi el protocol HTTP per a determinar operacions a ser executades sobre un conjunt de dades o directament obtenirles, formatades i sense les complicacions pròpies de realitzar aquesta tasca a un nivell més directe.

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 “acte”, tindria tots els camps relatius a un acte (títol, localització, data d'inici i finalització, 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 “Agenda de museus” i el dataset "Agenda de les biblioteques" tenen dades del tipus de contingut “acte”.

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 al recuperar la informació, també és possible recuperar les dades relacionades dins de la mateixa crida. La relacions es poden fer entre tipus de continguts o entre tipus de contingut i dataset (que no és altre cosa que un sub-conjunt de dades del tipus de contingut). Exemple: El tipus de contingut “recinte” estan relacionats amb el tipus de contingut “municipi” a través del codi INE, llavors, quan recuperéssem un recinte, també recuperem la informació del municipi on està ubicat.

Grup: Un grup és un conjunt o agrupació de camps.

Camp: Els camps defineixen els diferents valors que pot tenir un tipus de contingut. Els camps tenen diferents propietats:

Nom: Una etiqueta per referenciar el camp.

Nom màquina: Nom per identificar el camp en l'interacció amb la API. 

Pes: Valor que s'utilitza per ordenar els camps dins d'un registre.

Primari: Indica que aquest camp identifica el registre del que forma part, per tant, també té un valor únic dins el mateix dataset.

Multivaluat: Indica que el camp pot pendre més d'un valor.

Obligatori: Indica que en tot registre del dataset aquest camp ha de tenir un valor assignat.

Únic: Indica que el valor del camp no es pot repetir en la resta de registres d'un mateix dataset.

Tipus: Indica com està definit el valor del camp. Pot ser: booleà, data, decimal. email, enter, geolocalització, text, text llarg o url.

 

 

 

Mètodes i crides de l'API

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_

On _CRIDA_ te la forma parametre1/valor1/parametre2/valor2/ ... /parametreN/valorN

Totes les dades són accessibles en format CSV, XML, RDF-XML i JSON (per defecte). Els resultats en format XML, RDF-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 machine_name 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 machine_name.

Quadre resum de crides disponibles

Informació de l'estructura info/datasets
info/tipus
Selecció de dades dataset/[dataset]
tipus/[content_type]
Operadors de comparació camp-[field]/[value]
camp-[field]-like/[value]
camp-[field]-ornull/[value]
camp-[field]-greater/[value]
camp-[field]-greaterequal/[value]
camp-[field]-lower/[value]
camp-[field]-lowerequal/[value]
Operadors lògics camp-[field]/[value1]++[value2]
camp-[field]/[value1]||[value2]
Agregació agrega/[field]
Paginació pag-ini/[value1]/pag-fi/[value2]
pag-ini/[value1]
pag-fi/[value2]
Ordenació ord-[field]/asc
ord-[field]/desc
Format format/json
format/xml
format/csv
format/rdf-xml
Idioma idioma/ca
idioma/es
idioma/en
Ordenació per proximitat geord-camp/[field]/geord-cord/[lat,lng]
Filtre per proximitat ubicacio/[lat,lng]/geocamp/[field]/radi/[value]
Cerca de text lliure camp-all/[value]
camp-all-like/[value]

Tipus de camps i propietats

L'API de dades obertes consta de diferents tipus de camps i cada camp pot tenir diferents propietats:

Tipus de camps
text Camp de text curt. Fins a un màxim de 256 caràcters.
ltext Camp de text llarg. Més de 256 caràcters.
geo Coordenades de latitud i longitud. S'utilitza el punt pels decimals i la coma per separar la latitud de la longitud. Per exemple: 41.43535,2.134242.
url Camp URL o localitzador uniforme de recursos.
email Camp de correu electrònic.
date Camp de data amb el format 31/12/2017 12:00:00 
Relació Camp que relaciona el dataset amb un altre dataset

 

Propietats dels camps
Clau primària Camp identificador del recurs. Sempre està informat i és únic.
Multivaluat El camp permet més d'un valor.
Obligatori El camp és obligatori.
Únic El valor del camp és únic i no es repeteix en cap altre registre.

A l'apartat recuperació de la informació dels camps i l'estructura pots veure com consultar els tipus dels camps d'un dataset i les seves propietats.

Recuperació de la informació dels camps i de l'estructura

Crida

~/info/tipus{/tipus/machine_name}

~/info/datasets{/dataset/machine_name}

Paràmetres 

/info/tipus: Retorna les estructures (camps, grups i relacions) de TOTS els tipus de contingut definits a la API, no els valors dels seus camps. Amb aquesta crida es poden aconseguir els machine_name dels tipus de contingut.

/info/tipus/tipus/machine_name: Amb aquesta crida aconseguim de nou l'estructura, però en aquest cas, per a un únic tipus de contingut concret determinat pel machine_name d'aquest.

/info/datasets: Retorna les estructures (camps, grups i relacions) de TOTS els datasets definits a la API, no els valors dels seus camps. Amb aquesta crida es poden aconseguir els machine_name dels datasets.

/info/datasets/dataset/machine_name: Amb aquesta crida aconseguim de nou l'estructura, però en aquest cas, per a un únic dataset concret determinat pel machine_name d'aquest.

Exemples

https://do.diba.cat/api/info/tipus

https://do.diba.cat/api/info/tipus/tipus/acte

https://do.diba.cat/api/info/tipus/tipus/punt

https://do.diba.cat/api/info/datasets

https://do.diba.cat/api/info/datasets/dataset/municipis

https://do.diba.cat/api/info/datasets/dataset/comarques

Contingut relacionat: 

Consulta per dataset o tipus de contingut

Crida

~tipus/[content_type]

~dataset/[dataset]

Paràmetres 

/tipus/[content_type]: Retorna TOTS els datasets (estructurats i amb valors) que son del tipus de contingut especificat per content_type.

/dataset/[dataset]: Retorna els camps del dataset especificat per dataset.

Exemples

https://do.diba.cat/api/tipus/municipi

https://do.diba.cat/api/tipus/acte/pag-fi/100

https://do.diba.cat/api/tipus/punt

https://do.diba.cat/api/dataset/municipis

https://do.diba.cat/api/dataset/actesbiblioteques_ca

https://do.diba.cat/api/dataset/puntesports

 

Contingut relacionat: 

Filtre pel valor d'un camp

Crida

~/camp-[field]-like/[value]

Paràmetres

/camp-[field]-like/[value]: Retorna aquells camps d'un dataset o tipus de contingut que tinguin value en el camp identificat per field. Si s'utilitza la directiva -like es retornaran valors aproximats (p.ex: allà on value sigui substring).

Exemples

http://do.diba.cat/api/tipus/bibliobus/camp-nom/Bibliobús Montnegre

https://do.diba.cat/api/dataset/municipis/camp-municipi_transliterat/tiana

https://do.diba.cat/api/dataset/escenari/camp-titol-like/viaje

 Important!

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

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”
Contingut relacionat: 

Operador "agrega"

Crida

~/agrega/[field1]{/agrega/[field2]}

Paràmetres

/agrega/[field1]{/agrega/[field2]}: Retorna l'agregació de tots els camps especificats pels field# d'un mateix dataset.

Exemples

https://do.diba.cat/api/dataset/electes/agrega/carrec_persona/agrega/sexe

https://do.diba.cat/api/dataset/biblioteques/agrega/municipi_nom

 

Operadors "and" i "or"

Crida

~camp-[field]/[value1]++[value2]

~camp-[field]/[value1]||[value2]

Paràmetres

|| , ++: Retorna tots aquells camps que (sent multivaluats) tinguin:

  • || : value1 o value2.
  • ++ : value1 i value2.
Exemples

http://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-dies/Dilluns||Dijous

https://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-tags/Taller++Infants

Operadors "greater" i "greaterequal"

Crida

~/camp-[field]-greater/[value]

~/camp-[field]-greaterequal/[value]

Paràmetres

/camp-[field]-greater/[value]: retorna totes les dades amb el valor del camp amb field més gran que value.

/camp-[field]-greaterequal/[value]: retorna totes les dades amb el valor del camp amb field més gran o igual que value.

Exemples

https://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-data_inici-greater/datetime:2016-04-10_09:00:00

https://do.diba.cat/api/dataset/puntesports_detall/camp-punt_esport_nombre_espais-greaterequal/7

https://do.diba.cat/api/dataset/actesmuseus/camp-data_inici-greater/datetime:now

Operador "like"

Crida ~/camp-[field]-like/[value]
Paràmetres

/camp-[field]-like/[value]: retorna totes les dades del camp amb field amb un valor aproximat a value.

Exemples

https://do.diba.cat/api/dataset/municipis/camp-municipi_transliterat-like/castell

https://do.diba.cat/api/dataset/museus/camp-adreca_nom-like/roma

Contingut relacionat: 

Operadors "lower" i "lowerequal"

Crida

~/camp-[field]-lower/[value]

~/camp-[field]-lowerequal/[value]

Paràmetres

/camp-[field]-lower/[value]: retorna totes les dades d'un registre que tingui un camp amb field i amb valor més petit que value.

/camp-[field]-lowerequal/[value]: retorna totes les dades d'un registre que tingui un camp amb field i amb valor més petit o igual que value.

Exemples

https://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-data_inici-lower/datetime:2016-04-10_09:00:00

https://do.diba.cat/api/dataset/puntesports_detall/camp-punt_esport_nombre_espais-lowerequal/6

https://do.diba.cat/api/dataset/actesmuseus/camp-data_inici-lower/datetime:now

Operador "ornull"

Crida

~/camp-[field]-ornull/[value]

Paràmetres

/camp-[field]-ornull/[value]: retorna totes les dades d'un registre que tingui un camp amb field amb el mateix valor que value o NULL.

Exemples

https://do.diba.cat/api/dataset/actesbiblioteques_ca/camp-preu-ornull/10

Contingut relacionat: 

Cerca a tots els camps

Crida

~/camp-all/[value]

~/camp-all-like/[value]

Paràmetres

/camp-all/[value]: retorna tots els registres amb algun camp amb el mateix valor que value.

/camp-all-like/[value]: retorna tots els registres amb algun camp amb el mateix valor que value o aproximat.

Exemples

https://do.diba.cat/api/dataset/biblioteques/camp-all-like/berga

http://do.diba.cat/api/dataset/museus/camp-all/Roda de Ter

https://do.diba.cat/api/dataset/museus/camp-all-like/marina

Contingut relacionat: 

Paginació

Crida

~/pag-ini/[value1]

~/pag-fi/[value2]

~/pag-ini/[value1]/pag-fi/[value2]

Paràmetres

/pag-ini/[value1]: retorna els registres a partir del value1.

/pag-fi/[value2]retorna els registres fins al value2.

/pag-ini/[value1]/pag-fi/[value2]: retorna tots els registres des del value1 fins al value2.

Exemples

https://do.diba.cat/api/dataset/escenari/pag-ini/40/pag-fi/60

https://do.diba.cat/api/dataset/escenari/pag-ini/23

https://do.diba.cat/api/dataset/escenari/pag-fi/500

 Important!

Per motius de rendiment per defecte qualsevol consulta torna els 1000 primers resultats.

Ordenació

Crida

~/ord-[field]/asc

~/ord-[field]/desc

Paràmetres

/ord-[field]/ascretorna els registres ordenats ascendentment agafant com a camp d'ordenació field.

/ord-[field]/desc: retorna els registres ordenats descendentment agafant com a camp d'ordenació field.

Es pot ordenar per més d'un camp, tot i que l'ordre marca la jerarquia. 

Exemples

https://do.diba.cat/api/tipus/municipi/ord-municipi_nom/desc

https://do.diba.cat/api/tipus/municipi/ord-municipi_nom/asc

https://do.diba.cat/api/tipus/municipi/ord-comarca_nom/desc/ord-municipi_nom/asc

Ordenació per proximitat

Crida

~/geord-camp/[field]/geord-cord/[lat,lng]

Paràmetres

/geord-camp/[field]/geord-cord/[lat,lng]retorna els registres amb el camp field més propers geogràficament a [lat,lng]

Exemples

https://do.diba.cat/api/dataset/municipis/geord-camp/localitzacio/geord-cord/41.34220,-2.2678

Contingut relacionat: 

Filtre per proximitat

Crida

~/ubicacio/[lat,lng]/geocamp/[field]/radi/[value]

Paràmetres

/ubicacio/[lat,lng]/geocamp/[field]/radi/[value]retorna els registres amb el camp field més propers geogràficament a [lat,lng] amb radi value

Exemples

http://do.diba.cat/api/dataset/municipis/ubicacio/41.5606948,1.523511/geocamp/localitzacio/radi/

Contingut relacionat: 

Calendaris: Tipat i valors màgics

Alguns tipus de camps permeten tipat, això ens permet indicar que el filtre, la comparació o l'ordenació que estem indicant s'ha de fer utilitzant una conversió de format concreta enlloc de fer-ho per text.

Per exemple, si volem recuperar  tots els actes posteriors al 23/06/2016 podem indicar-li que per fer la comparació utilitzi una data i ignori la hora amb el tipat ":date": camp-[field]-greater/date:2016-06-23, o si volem els actes entre les 9h del matí i les 17h de la tarda podem utilitzar el tipat ":datetime" perquè tingui en compte els hores i utilitzar dos filtres: camp-[field]-greaterequal/datetime:2016-06-23_09:00:00/camp-[field]-loweerequal/datetime:2016-06-23_17:00:00

Tipats disponibles:

  • date: YYYY-MM-DD
  • datetime: YYYY-MM-DD_hh:mm:ss

Els valors màgics són variables reservades que defineix el sistema, i que permet, per exemple recuperar les activitats del dia amb una URL estàtica sense haver-li de passar el dia actual podent inscrutar dades en webs estàtiques a tarvés de widgets.

Valors màgics disponibles

  • date:now (dia actual)
  • datetime:now (dia i hora actuals)

Exemples:

Llista d'actes que comencen avui: https://do.diba.cat/api/tipus/acte/camp-data_inici/date:now

 

Tokens

No es necessita cap token per utilitzar l'API de dades obertes i per consultar qualsevol dada de datasets públics.

Els tokens són seqüències de valors alfanumèrics que es poden afegir a les crides de l'API i que s'utilitzen amb propòstis estadístics i per donar accés a datasets privats.

Els tokens els facilita la Diputació de Barcelona i aquests són variables en funció d'un algoritme públic que fa que el token vagi canviant cada dia i d'una clau privada.

Hi ha tres mètodes diferents per fer una crida amb token:

  • A través dels HEADERS de la crida HTTP (variable diba-token)
  • A través del mètode POST (variable token)
  • A través del mètode GET (_CRIDA_API_/token/{valor})

Per motius de seguretat i cachejat de la resposta es recomana utilitzar preferentment pels tokens HEADERS o POST i crides HTTPS, i en últim terme GET i HTTP.

 

Exemple PHP/cURL

Token via HEADER

$ch = curl_init($crida);
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ['diba-token: ' . $token],
  CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);

Token via POST

$ch = curl_init($crida);
curl_setopt_array($ch, [
  CURLOPT_POSTFIELDS => ['token' => $token],
  CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);

Token via GET

$ch = curl_init($crida . '/token/' . $token);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);

Format de sortida

Crida

~/format/json
~/format/xml
~/format/csv
~/format/rdf-xml

Paràmetres

/format/jsonretorna el dataset en el format JSON, aquesta és la opció per defecte.

/format/xml: retorna el dataset en el format XML.

/format/csv: retorna el dataset en el format CSV.

/format/rdf-xml: retorna el dataset en el format RDF-XML.

Exemples

http://do.diba.cat/api/dataset/actesbiblioteques_ca/format/rdf-xml

https://do.diba.cat/api/dataset/municipis/format/xml

Formats disponibles

JSON https://do.diba.cat/api/dataset/municipis (per defecte)

 http://do.diba.cat/api/dataset/municipis/format/json

XML https://do.diba.cat/api/dataset/municipis/format/xml

CSV https://do.diba.cat/api/dataset/municipis/format/csv

RDF https://do.diba.cat/api/dataset/municipis/format/rdf-xml

Contingut relacionat: 

Selecció de l’idioma

Crida

~/idioma/ca

~/idioma/es

~/idioma/en

Paràmetres

~/idioma/ca: retorna el dataset en català si es troba disponible.

~/idioma/es: retorna el dataset en castellà si es troba disponible.

~/idioma/en: retorna el dataset en anglès si es troba disponible.

Exemples

https://do.diba.cat/api/dataset/parcsequipaments_ca

https://do.diba.cat/api/dataset/parcsequipaments/idioma/ca

Combinatòria de criteris i exemples reals

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: https://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 diversos:

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

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

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

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

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

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

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

Tots els actes de qualsevol conjunt de dades:
https://do.diba.cat/api/tipus/acte/pag-fi/100

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

Registres modificats avui en el dataset de biblioteques:
https://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:
https://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:
https://do.diba.cat/api/dataset/biblioteques/format/json2/ubicacio/41.37,2.18/geocamp/localitzacio/radi/1000

Contingut relacionat: 

Memòria cau i refresc de les dades

L'API té un sistema de memòria cau per millorar el rendiment que evita haver de processar les mateixes consultes de forma repetitiva. Per tant, quan es fa una crida a l'API aquesta s'enmagatzema en una memòria cau del servidor i, si se li torna a demanar la mateixa petició exacta, torna la resposta emmagatzemada directament de la memòria cau.

Aquesta memòria cau s'anomena APICache i té una persistència de 12 hores, així que tota crida realitzada de forma repetitiva es manté invariable durant almenys 12 hores, encara que durant aquest interval hi hagi hagut una modificació de les dades. Quan es modifica una dada l'API pot trigar de 0 a 12 hores a servir la modificació.

Per saber si les dades que estàs consumint s'han generat en aquell moment o han estat servides directament per la memòria cau, les respostes incorporen una propietat anomenada cache al final de totes les respostes. Aquesta propietat indica el dia i hora exactes en què es va guardar aquella resposta en memòria cau. Si les dades no incorporen aquesta propietat, és perquè la resposta s'ha generat en aquell precís moment i, per tant, no s'han servit de l'APICache.

Exemple: cache:"2017-06-07 03:13:19"

La data i hora estan en temps universal UTM.

Per tant, a la freqüència d'actualització de les dades que indiquen els datasets cal afegir-hi un marge adicional de 12 hores, que és el temps màxim que pot trigar a propagar-se el canvi a través de la memòria cau de l'API.

Versionat de l'API: Changelog

1.11 Lepista - 02/06/2017

  • Suport de crides amb JSONP: format/json?callback=jsonParser
  • Bugfixing, millores de rendiment i millores en la visualització i la navegació.
  • Noves opcions en la incrustació externa de visors: Mostra el botó per incrustar

1.10 Kretzschmaria - 06/03/2017

  • Millores en les gràfiques d'estadístiques d'ús públiques.
  • Caixes d'informació adicional en els visors: estadístiques d'ús del dataset, exemples de crides de l'API i enllaços ràpids a la documentació.
  • Millores importants de rendiment.
  • Millores en la visualització dels filtres dels visors.
  • Millores en la visualització del visor tipus Mapa.
  • Incorporació d'informació sobre els camps dels datasets i la seva descripció en els visors.

1.9 Junghuhnia - 18/01/2017

  • Afegides les estadístiques per visors a les estadístiques: https://do.diba.cat/stats/
  • Nou filtre dinàmic per columna en els visors tipus taula dels datasets.
  • Nova sortida RDF-XML: format/rdf-xml.
  • Noves opcions per a seleccionar el tipus d'agregació en el visor mapa.
  • Nova opció d'exportació de totes les dades en format XML-RDF.

1.8 Inocybe - 05/09/2016

1.7 Helvella - 02/08/2016

  • Nou visor de dades: Calendari.

1.6 Gírgola - 15/07/2016

  • CANVI A L'API: Eliminem el doble format de sortida format/json i format/json2, en un únic format de sortida simplificada json. Ara els tres formats de sortida disponibles són: json, xml i csv, en cas de no especificar-se o indicar un format de sortida incorrecte tornarà la sortida json.
  • Els datasets incorporen més metadades a la sortida com: paraules clau, freqüència d'actualització, llicència, sector, tema, responsable de les dades i referències. Exemple: http://do.diba.cat/api/info/datasets
  • Nou camp cache: "YYYY-MM-DD HH:MM:SS". El camp indica el dia i hora en que es va guardar la resposta a la memòria cau del sistema. Si el camp no existeix és perquè s'ha servit la dada directament de base de dades, si existeix indica quan es va guardar la resposta a la memòria cau. La vida màxima de la memòria cau és de 24 hores.

1.5 Fredolic - 23/05/2016

  • Visor de dades en format mapa: https://do.diba.cat/data/
  • Possiblitat de cerca per text lliure en tots els camps: camp-all/text o camp-all-like/text.
  • L'operador like s'ha fet case insensitive.
  • Datasets multilingües: es pot filtrar per codi d'idioma i recuperar un mateix dataset en tots els diferents idiomes disponibles, exemple: api/dataset/parcsequipaments/idioma/es, api/dataset/parcsequipaments/idioma/ca.
  • Generació d'un codi d'incrustació en els visors de dades per a webs externes via iframe.
  • L'exportació de dades a XML, JSON o CSV quan estàs en un visor respecta els filtres i l'ordenació triada.
  • S'ha afegit una capçalera crossdomain a l'API per permetre crides AJAX externes.
  • La incrustació incorpora via iframe el botó d'exportació de dades.

1.4 Escarlet - 16/07/2015

  • Visor de dades en format taula: https://do.diba.cat/data/
  • Visor de dades per tipus de contingut.
  • Visor de dades per conjunt de dades.
  • Filtres en el visor de dades per camp, municipi o tema.
  • Exportació de les dades filtrades en el visor en els formats: CSV, JSON i XML.
  • Nova crida de l'API per agregar contingut per a consultes tipus GROUP BY: agrega/machinename. Es permet agregar per mútilples camps i la resta de filters són aplicables (flitres, formats o paginació). Per exemple, recompte de càrrecs electes per sexe i municipi (codi INE): api/dataset/electes/agrega/codi_ine/agrega/sexe.

1.3 Dent de rata - 21/05/2015

  • Nou camp a la sortida de tots els elements: "_lastChange", amb la data de creació o darrera modificació del registre.
  • Es poden recuperar, ordenar i filtrar dades per data de modificació del registre, per exemple: camp-_lastChange-greaterequal/date:2015-05-21.

1.2 Camagroc - 10/12/2014

  • Nou identificar únic universal per a qualsevol entitat: _id
  • A partir d'ara la paginació comença per 1 enlloc de per 0: pag-ini/1 (si es passa un 0 es considerarà un 1)
  • S'ha modificat el funcionament de la cerca LIKE amb camps multivaluats, ara evalua la condició valor a valor enlloc d'evaluar tot el string de valors.
  • Sistema de tokens i credencials per poder modular recursos (thresholding) i accesos.
  • DEPRECAT: Nova sortida JSON amb estructura simplificada format/json2 (en una futura versió aquesta serà la sortida per defecte format/json).
  • Eliminats els salts de línea innecesaris de la sortida en XML: format/xml
  • Millora del rendiment quan es filtra per dataset o tipus de contingut: dataset/machinename i tipus/machinename
  • Millora del rendiment quan es filtra o s'ordena per proximitat: geord-camp/localitzacio/geord-cord/41.453889,2.211111

1.1 Bec de perdiu - 21/07/2014

  • S'incorpora l'operador OR a les crides de paràmetres: camp-machinename/valor1||valor2
  • S'incorpora l'operador AND a les crides de paràmetres: camp-machinename/valor1++valor2
  • S'incorpora l'operador OR NULL a les crides de l'API: camp-machinename-ornull/valor
  • S'extenen les relacions entre conjunts de dades i ara poden ser de dos tipus ContentType/Dataset o ContentType/ContentType.
  • Les respostes amb relacions entre conjunts de dades no incrustades, al ser de 1 a N, incorporen un contador per evitar que l'aplicació hagi de fer una segona crida per mirar quants registres compleixen la relació.
  • CANVI A L'API: Es canvia el format de les dates per YYYY-MM-DD, tant a les crides com a la sortida per facilitar l'ordenació i millorar el rendiment (abans era DD-MM-YYYY).
  • S'afegeix el tipat date a les crides: camp-machinename/date:2014-10-27
  • S'afegeix el tipat datetime a les crides: camp-machinename/datetime:2014-10-27_09:00:00
  • CANVI A L'API: Quan es filtra o s'ordena per data s'ha d'especificar obligatòriament el tipat a la crida: camp-machinename/date:2014-11-21
  • S'afegeix la variable 'now' per a les crides amb dates, cosa que et permet fer crides tipus: camp-data_inici-greaterequal/datetime:now
  • CANVI A L'API: Es simplifica la sintaxis de la crida d'ordenació: ord-machinename/desc (abans era: ord-camp/machinename/ord-sentit/asc).

1.0 Apagallums

  • Versió inicial de l'API REST.

Exemples de codificació

Pets consultar exemples de codificació que utilitzen l'API de dades obertes perparats per a ser reutilitzats.

Exemples de codi

 

DKAN API

DKAN (la plataforma de gestió de dades de codi obert basada en Drupal, sobre la qual està construït aquest portal) ofereix una API per recuperar informació del catàleg de dades que normalment s'utilitza per sindicar continguts amb altres portals. L'APIs de DKAN es pot fer servir per recuperar metadades dels datasets.

L'API de DKAN és una API addicional i complementària a la nostra API de dades obertes.

Exemples de crides de l'API DKAN
Llista dels datasets disponibles https://dadesobertes.diba.cat/api/3/action/package_list
Catàleg de dades DCAT en format JSON https://dadesobertes.diba.cat/catalog.json
Catàleg de dades DCAT amb format XML https://dadesobertes.diba.cat/catalog.xml
Llista de recursos en format JSON https://dadesobertes.diba.cat/data.json
Llista de publicadors de dades https://dadesobertes.diba.cat/api/3/action/group_list
Catàleg de dades amb recursos https://dadesobertes.diba.cat/api/3/action/current_package_list_with_res...

Pots consultar més informació sobre les APIs de DKAN en aquest web.