Visualització de contingut web

Informació per a reutilizadors

Introducció

En aquesta secció del portal de Dades Obertes de la Generalitat Valenciana es proporciona informació d'utilitat per a desenvolupadors d'aplicacions, així com per a usuaris amb un perfil més tècnic.

Per a més informació sobre l'API de CKAN consulte el document que hem elaborat sobre aquest tema. 

 

Què són les API?

Una API és un conjunt de protocols i definicions que s'utilitzen per a integrar i desenvolupar el programari de les aplicacions. Les sigles API (application programming interface) signifiquen interfície de programació d'aplicacions. 

 

En el portal de Dades Obertes de la Generalitat Valenciana proporcionem dos tipus d'API:

  • API de gestió del catàleg: API que serveix per a consultar i gestionar la informació del catàleg, com són els recursos, conjunts de dades o datasets, etiquetes, temes, etc.
  • API de consulta sobre els recursos CSV: API que permet consultar i filtrar la informació continguda dins d'un CSV d'un recurs.

Tant les API de gestió del catàleg com les API de consulta sobre recursos CSV ofereixen com a serveis web REST en format JSON.

La majoria dels mètodes es poden cridar també directament per URL afegint els paràmetres que siguen necessaris. En l'anomenada a aquests mètodes es pot incloure el paràmetre callback perquè la resposta es retorne en format JSONP per al seu posterior ús amb Javascript.
 

API de gestió del catàleg

Aquesta és l'API que ofereix l'aplicatiu CKAN per a gestionar el catàleg de datasets. Podem accedir a aquesta API a través de l'URL https://dadesobertes.gva.es/va/api/1/util/snippet/api_info.html?resource_id=9327e3fe-d271-4f35-9e85-0ca5dd39031d afegint el nom del mètode al qual volem accedir.
 

Mitjançant aquesta API es pot accedir a la mateixa informació que està accessible en el portal de Dades Obertes de la Generalitat. És a dir, pot ser d'utilitat per a un usuari per a conéixer la informació que es troba disponible en el portal: recursos, datasets, etiquetes, temes, etc.

 

Alguns exemples de mètodes que es poden utilitzar amb aquesta API són els següents:

  • current_package_list_with_resources: retorna un llistat de tots els datasets actuals amb els seus recursos
  • package_search: búsqueda d'un dataset determinat dins del catàleg
  • resource_search: búsqueda d'un recurs determinat dins del catàleg
  • package_show: retorna les metadades d'un recurs
  • resource_show: retorna les metadades d'un recurs
  • group_list: llista els temes del portal
 

Per a utilitzar aquesta API és molt útil consultar el llistat complet de mètodes en la GUIA API de CKAN.

 

API de consulta sobre els recursos CSV

Aquesta API permet actuar sobre un recurs CVS concret del portal. Quan es puja un CSV a l'aplicació, es crea de manera interna una taula en la base de dades del datastore per a aquest recurs. L'API de consulta sobre recursos CSV és precisament l'API del datastore, que permet realitzar consultes directament sobre aquestes taules.

En el portal de Dades Obertes de la Generalitat oferim un endpoint per a tots els CSV de la plataforma, que permet buscar dins del recurs en funció d'una sèrie de criteris de cerca que s'afigen com a paràmetres a la crida.

Aquest endpoint és el següent:

Per a poder realitzar una consulta sobre un recurs en concret, s'ha de definir com a paràmetre l'ID del recurs sobre el qual es vol fer la consulta.

Per exemple, per a fer una consulta sobre el recurs del dataset "Registre de centres, serveis i establiments sanitaris 2020" realitzaríem la següent consulta:

 

Com obtindre l'identificador d'un recurs?

Per a obtindre l'identificador (ID) d'un recurs ha de tindre en compte que els URL dels recursos en el portal són del tipus: https://dadesobertes.gva.es/es/dataset/name-dataset/resource/identificador

On identificador és l'ID del recurs en qüestió. Amb la qual cosa simplement navegant pels recursos del portal pot obtindre els identificadors dels recursos per a realitzar la consulta a l'API amb aquest ID.

 

Com obtindre els noms dels camps?

Per a obtindre els noms dels camps d'un recurs i poder realitzar consultes amb l'API, únicament hem d'accedir a la previsualització del recurs CSV.

Per exemple, si accedim al recurs "Centres Sanitaris 2020" i ens fixem en la vista de l'explorador de dades, podrem veure que el recurs té unes capçaleres que en aquest cas en qüestió són: ANY, COD_PROV, NOM_PROV, COD_MUN, NOM_MUN, NUM_REGISTRE, NOM_CENTRE, etc.

Tenint l'ID del recurs i aquests camps podrem realitzar consultes, tal com expliquem en el següent apartat.
 

Com realitzar consultes amb datastore_search?

Recordem que l'endpoint per a realitzar les consultes és: https://dadesobertes.gva.es/api/3/action/datastore_search
 
Els paràmetres que es poden utilitzar amb aquest endpoint són:
  • resource_id (string - obligatori) - id del recurs CSV sobre el qual volem buscar.
  • filters (diccionario) - condicions que s'han de complir. Exemple: {"NOM_PROV": "%VALENCIA%"}.
  • q (string o diccionari) - búsqueda en full text. Es pot especificar un string per a buscar-lo en tots els camps o un diccionari per a buscar en camps concrets, p. ex.: {"key1": "a", "key2": "b"}.
  • distinct (boolean) - retorna només les files diferents.
  • plain (boolean) - tracta la consulta com si fora un text pla.
  • language (string) - llenguatge de la consulta en full text.
  • limit (int) - nombre màxim de resultats. Per defecte retorna 100 resultats.
  • offset (int) - nombre de resultats que s'han de saltar. Útil per a fer una paginació de resultats.
  • fields (string) - llistat de camps que s'inclouran en la resposta. Per defecte retorna tots els camps amb el mateix ordre que en el CSV.
  • sort (string) - nom dels camps per als quals ordenar separats per comes: "ANY, NOM_PROV".
  • include_total (boolean) - Retorna el recompte total de registres coincidents (opcional, per defecte: true).

Exemple de consulta a datastore_search:

Imaginem que volem buscar els centres sanitaris de la província de València. Per a això, partint del dataset https://dadesobertes.gva.es/es/dataset/san-reg-centros-2020 i del recurs https://dadesobertes.gva.es/es/dataset/san-reg-centros-2020/resource/587f127a-469c-4c9c-819d-0d4b85cb4b1f obtindrem l'ID del recurs (587f127a-469c-4c9c-819d-0d4b85cb4b1f) i el nom del camp sobre el qual volem realitzar la cerca (NOM_PROV).
 

Per tant, els paràmetres d'entrada seran:

  • resource_id: 587f127a-469c-4c9c-819d-0d4b85cb4b1f
  • q:  {"NOM_PROV" : "VALENCIA"}
 

Amb això, l'url per a la consulta seria la següent:

 

Com obtindre dades actualitzades dels recursos?

Per a obtindre les dades més recents corresponents a una entrada d'un recurs d'un conjunt de dades s'ha de seleccionar l'últim recurs actualitzat d'aquest. Per a això ens hem de fixar en la metadada "last_modified" dins de la resposta a la petició i seleccionar aquell més pròxim a la data actual.

Podem seguir el següent procediment com a exemple per a obtindre els recursos del conjunt de dades de Casos de COVID per grups d'edat i sexe:

Primer, recuperar els identificadors dels recursos d'un determinat conjunt de dades per mitjà d'una consulta a l'API similar a la següent:

https://dadesobertes.gva.es/api/3/action/package_search?q=covid-19-dades-de-casos-i-persones-mortes-per-grup-edat-i-sexe-acumulades-des-del-31-01-2020

Segon, observar que en el resultat de la consulta està en format JSON, i dins del camp [result][resources] està el llistat de recursos d'aquest conjunt de dades. En aqueix llistat JSON de recursos, la metadada "last_modified" proporciona informació sobre la data de l'última actualització del recurs.

Per a això es pot implementar en l'aplicació que està desenvolupant una funció que recórrega tots els recursos d'un determinat conjunt de dades i seleccione el més actualitzat.

Finalment, una vegada dispose de l'últim recurs actualitzat, ha de realitzar una consulta a l'API del datastore amb el 'id' del recurs en qüestió, com la següent:

https://dadesobertes.gva.es/api/3/action/datastore_search?resource_id=6df2cca7-3f64-4f08-962c-62ddc21e67a0

I si es desitja en aquesta última petició a l'API del datastore es pot passar paràmetres com a filtres.

 

Com evitar errors en el navegador per no incloure la capçalera CORS?

Si la petició que l'aplicació des del costat del client que telefona a l'API de CKAN està dins dels mètodes permesos (com un GET) és bloquejada per no incloure una capçalera CORS (cross-origin resource sharing en castellà intercanvi de recursos d'origen creuat) es pot accedir a la informació tractant la resposta com una callback en format JSON, com es pot veure en el següent codi, on es realitza una anomenada a una funció Javascript per a mostrar tot el contingut d'un recurs:

 

Data d'actualització del text: març 2023
Data de creació: octubre 2020