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?
- 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.
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.
- 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
-
datastore_search: https://dadesobertes.gva.es/api/3/action/datastore_search
https://dadesobertes.gva.es/api/3/action/datastore_search?id=587f127a-469c-4c9c-819d-0d4b85cb4b1f
¿Cómo obtener el identificador de un recurso?
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?
¿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%"}.
- q (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:
- resource_id: 587f127a-469c-4c9c-819d-0d4b85cb4b1f
- q: {"NOM_PROV" : "VALENCIA"}
¿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