Web Content Display

Información para reutilizadores

Introducción

En esta sección del portal de Dades Obertes de la Generalitat Valenciana se proporciona información de utilidad para desarrolladores de aplicaciones así como para usuarios con un perfil más técnico.

Para más información sobre la API de CKAN consulte el documento que hemos elaborado sobre este tema. 

 

¿Qué son las API?

Una API es un conjunto de protocolos y definiciones que se utilizan para integrar y desarrollar el software de las aplicaciones. Las siglas API (application programming interface) significan interfaz de programación de aplicaciones. 
 
En el portal de Dades Obertes de la Generalitat Valenciana proporcionamos dos tipos de API:
  • API de gestión del catálogo: API que sirve para consultar y gestionar la información del catálogo, como son los recursos, conjuntos de datos o datasets, etiquetas, temas, etc.
  • API de consulta sobre los recursos CSV: API que permite consultar y filtrar la información contenida dentro de un CSV de un recurso.
 
Tanto las API de gestión del catálogo, como las API de consulta sobre recursos CSV ofrecen como servicios web REST en formato JSON.
 
La mayoría de los métodos se pueden llamar también directamente por URL añadiendo los parámetros que sean necesarios. En la llamada a estos métodos se puede incluir el parámetro callback para que la respuesta se devuelva en formato JSONP para su posterior uso con Javascript.
 

API de gestión del catálogo

Esta es la API que ofrece el aplicativo CKAN para gestionar el catálogo de datasets. Podemos acceder a esta API a través de la URL https://dadesobertes.gva.es/va/api/1/util/snippet/api_info.html?resource_id=9327e3fe-d271-4f35-9e85-0ca5dd39031d añadiendo el nombre del método al que queremos acceder.

Mediante esta API se puede acceder a la misma información que está accesible en el portal de Dades Obertes de la Generalitat. Es decir, puede ser de utilidad para un usuario para conocer la información que se encuentra disponible en el portal: recursos, datasets, etiquetas, temas, etc.
 
Algunos ejemplos de métodos que se pueden utilizar con esta API son los siguientes:
  • current_package_list_with_resources: devuelve un listado de todos los datasets actuales con sus recursos
  • package_search: búsqueda de un dataset determinado dentro del catálogo
  • resource_search: búsqueda de un recurso determinado dentro del catálogo
  • package_show: devuelve lo metadatos de un dataset
  • resource_show: devuelve los metadatos de un recurso
  • group_list: lista los temas del portal

Para utilizar esta API es muy útil consultar el listado completo de métodos en la  GUÍA API de CKAN. 

 

API de consulta sobre los recursos CSV

Esta API permite actuar sobre un recurso CVS concreto del portal. Cuando se sube un CSV a la aplicación, se crea de forma interna una tabla en la base de datos del datastore para este recurso. La API de consulta sobre recursos CSV es precisamente la API del datastore, que permite realizar consultas directamente sobre estas tablas. 
 
En el portal de Dades Obertes de la Generalitat ofrecemos un endpoint para todos los CSV de la plataforma, que permite buscar dentro del recurso en función de una serie de criterios de búsqueda que se añaden como parámetros a la llamada. 
 
Este endpoint es el siguiente:
Para poder realizar una consulta sobre un recurso en concreto, se debe definir como parámetro el ID del recurso sobre el que se quiere hacer la consulta.
 
Por ejemplo, para hacer una consulta sobre el recurso del dataset "Registro de centros, servicios y establecimientos sanitarios 2020" realizaríamos la siguiente consulta: 

https://dadesobertes.gva.es/api/3/action/datastore_search?id=587f127a-469c-4c9c-819d-0d4b85cb4b1f

 

¿Cómo obtener el identificador de un recurso?

Para obtener el identificador (ID) de un recurso debe tener en cuenta que las URL de los recursos en el portal son del tipo: https://dadesobertes.gva.es/es/dataset/name-dataset/resource/identificador

Donde identificador es el ID del recurso en cuestión. Con lo cual simplemente navegando por los recursos del portal puede obtener los identificadores de los recursos para realizar la consulta a la API con ese ID. 

 

¿Cómo obtener los nombres de los campos?

Para obtener los nombres de los campos de un recurso y poder realizar consultas con la API, únicamente tenemos que acceder a la previsualización del recurso CSV. 
 
Por ejemplo, si accedemos al recurso "Centros Sanitarios 2020" y nos fijamos en la vista del explorador de datos, podremos ver que el recurso tiene unas cabeceras que en este caso en cuestión son: ANYO, COD_PROV, NOM_PROV, COD_MUN, NOM_MUN, NUM_REGISTRO, NOM_CENTRO, etc. 
 
Teniendo el ID del recurso y estos campos podremos realizar consultas, tal y como explicamos en el siguiente apartado.
 
 

¿Cómo realizar consultas con datastore_search?

Recordemos que el endpoint para realizar las consultas es: https://dadesobertes.gva.es/api/3/action/datastore_search

Los parámetros que se pueden utilizar con este endpoint son:

  • resource_id (string - obligatorio) - id del recurso CSV sobre el que queremos buscar.
  • filters (diccionario) - condiciones que se han de cumplir. Ejemplo: {"NOM_PROV": "%VALENCIA%"}.
  • (string o diccionario) - búsqueda en full text. Se puede especificar un string para buscarlo en todos los campos o un diccionario para buscar en campos concretos, p.e: {"key1": "a", "key2": "b"}.
  • distinct (boolean) - retorna sólo las filas diferentes.
  • plain (boolean) - trata la consulta como si fuese un texto plano.
  • language (string) - lenguaje de la consulta en full text.
  • limit (int) - número máximo de resultados. Por defecto retorna 100 resultados.
  • offset (int) - número de resultados que se deben saltar. Útil para hacer una paginación de resultados.
  • fields (string) - listado de campos que se incluirán en la respuesta. Por defecto retorna todos los campos con el mismo orden que en el CSV.
  • sort (string) - nombre de los campos para los que ordenar separados por comas: "ANYO, NOM_PROV".
  • include_total (boolean) - Deuvelve el recuento total de registros coincidentes (opcional, por defecto: true).

 

Ejemplo de consulta a datastore_search:

Imaginemos que queremos buscar los centros sanitarios de la provincia de Valencia. Para ello, partiendo del dataset https://dadesobertes.gva.es/es/dataset/san-reg-centros-2020 y del recurso https://dadesobertes.gva.es/es/dataset/san-reg-centros-2020/resource/587f127a-469c-4c9c-819d-0d4b85cb4b1f obtendremos el ID del recurso (587f127a-469c-4c9c-819d-0d4b85cb4b1f) y el nombre del campo sobre el que queremos realizar la búsqueda (NOM_PROV).
 
Por lo tanto, los parámetros de entrada serán: 
  • resource_id: 587f127a-469c-4c9c-819d-0d4b85cb4b1f
  • q:  {"NOM_PROV" : "VALENCIA"}
 
Con ello, la url para la consulta sería la siguiente:

https://dadesobertes.gva.es/api/3/action/datastore_search?resource_id=587f127a-469c-4c9c-819d-0d4b85cb4b1f&q={"NOM_PROV"%3A"%25VALENCIA%25"}

 

¿Cómo obtener datos actualizados de los recursos?

Para obtener los datos más recientes correspondientes a una entrada de un recurso de un conjunto de datos se debe seleccionar el último recurso actualizado del mismo. Para ello nos debemos fijar en el metadato "last_modified" dentro de la respuesta a la petición y seleccionar aquel más cercano a la fecha actual.

Podemos seguir el siguiente procedimiento como ejemplo para obtener los recursos del conjunto de datos de Casos de COVID por grupos de edad y sexo:

Primero, recuperar los identificadores de los recursos de un determinado conjunto de datos por medio de una consulta a la API similar a la siguiente: 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 

Segundo, observar que en el resultado de la consulta está en formato JSON, y dentro del campo [result][resources] está el listado de recursos de este conjunto de datos. En ese listado JSON de recursos, el metadato "last_modified" proporciona información sobre la fecha de la última actualización del recurso.

Para lo cual se puede implementar en la aplicación que está desarrollando una función que recorra todos los recursos de un determinado conjunto de datos y seleccione el más actualizado.

Finalmente, una vez disponga del último recurso actualizado, debe realizar una consulta a la API del datastore con el 'id' del recurso en cuestión, como la siguiente: https://dadesobertes.gva.es/api/3/action/datastore_search?resource_id=6df2cca7-3f64-4f08-962c-62ddc21e67a0

Y si se desea en esta última petición a la API del datastore se puede pasar parámetros como filtros. 

 

¿Cómo evitar errores en el navegador por no incluir la cabecera CORS?

Si la petición que la aplicación desde el lado del cliente que llama a la API de CKAN está dentro de los métodos permitidos (como un GET) es bloqueada por no incluir una cabecera CORS (cross-origin resource sharing en castellano intercambio de recursos de origen cruzado) se puede acceder a la información tratando la respuesta como una callback en formato JSON, como se puede ver en el siguiente código, donde se realiza una llamada a una función JavaScript para mostrar todo el contenido de un recurso: 

 

 

Fecha de actualización del texto: marzo 2023
Fecha de creación: octubre 2023