Visor de contenido web

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. 
 

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

¿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: 

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: