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.

 

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/api/3/action/ 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:

 

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: