L’Espai de dades de l’Economia Social i Solidària (https://espaidedades.dadess.cat/) està basat en CKAN (https://ckan.org/). CKAN ofereix una sèrie de mètodes per a poder accedir als diferents datasets de forma automàtica, cosa que permet tenir processos recurrents que alimentin les bases de dades de les organitzacions, podent creuar les dades de l’espai de dades amb les dades pròpies.
En aquest article veurem com accedir a les dades dels datasets, principalment a través de Python.
Llibreries necessàries
La llibreria necessària per a poder executar els procediments de l’API de CKAN és ckanapi (https://pypi.org/project/ckanapi).
Altres llibreries que ens poden ser útils per a poder tractar les dades són:
- pandas: per a transformar les dades baixades en dataframes i operar sobre ells.
- sqlalchemy: per a accedir a base de dades i poder, per exemple, inserir les dades del dataset a una altra base de dades.
Accedir a les dades d’un dataset
El primer que necessitem per a poder accedir a l’API de CKAN és configurar el client.
from ckanapi import RemoteCKAN
rc = RemoteCKAN('https://espaidedades.dadess.cat/')
En cas que als datasets que vulguem accedir siguin privats també s’ha d’afegir el paràmetre apikey.
rc = RemoteCKAN('https://espaidedades.dadess.cat/'
, apikey='ckan_apikey-ckan_apikey-ckan_apikey'
)
Després, per a accedir a les dades d’un dataset, necessitem saber l’identificador del dataset.
Aquest identificador el podem obtenir des de la UI quan entrem al recurs al que volem accedir.
Un cop ja tenim l’identificador podem accedir a les dades mitjançant la funció datastore_search (https://docs.ckan.org/en/latest/maintaining/datastore.html#ckanext.datastore.logic.action.datastore_search).
Els paràmetres principals d’aqeusta funció son:
- resource_id: identificador del recurs al que volem accedir.
- limit: nombre de files retornades.
- offset: files a saltar respecte l’inici.
- fields: camps a retornar (per defecte, tots).
- filters: diccionari de filtres a aplicar.
Els filtres són condicions AND de tipus simple. Per exemple:
filters = {
"fase_publicacio": [
"Alerta futura",
"Formalització"
],
"identificacio_adjudicatari": ""
}
És eqiuvalent a:
fase_publicacio in ('Alerta futura', 'Formalització') and identificacio_adjudicatari=''
Podeu obtenir més informació sobre els filtres a: https://docs.ckan.org/en/latest/maintaining/datastore.html#filters
Un cop executem la funció CKAN ens retornarà un diccionari amb els següents camps principals:
- fields: llista dels camps seleccionats amb l’id, el tipus de dada i la descripció. Ex: {'id': 'type', 'type': 'varchar', 'info': {'label': 'Tipus'}}
- records: llista amb els resultats Ex. {'type': 'subvencions', 'links': 'https://api.diba.cat/dadesobertes/cido/v1/subvencions/19156876'}
- total: total de files del dataset amb els filtres posats. Ens serveix per tal de poder saber si, quan fem paginació, hem llegit ja totes les dades. També podem saber que ja hem llegit totes les dades del recurs quan records retorna un array buit.
Podem fer la mateixa crida per curl a través d’aquesta comanda:
curl https://espaidedades.dadess.cat/api/action/datastore_search \
-d '
{
"resource_id": "e7185c7a-5d06-44c6-9d24-89efb8e5b76e",
"limit": 5,
"filters": {
"fase_publicacio": [
"Alerta futura",
"Formalització"
],
"identificacio_adjudicatari": ""
}
}'
En cas que sigui un recurs privat s’ha d’afegir el camp: X-CKAN-API-Key
El nom d’aquest camp pot variar en les diferents instal·lacions de CKAN i està configurat al fixeer ckan.ini a la propietat: apitoken_header_name .
Obtenció de la informació del dataset
Una altra funcionalitat interessant és la d’aconseguir la definició del recurs, amb els camps disponibles. Ho podem fer mitjançant la funció datastore_info (https://docs.ckan.org/en/latest/maintaining/datastore.html#ckanext.datastore.logic.action.datastore_info ).
Aquesta funció s’invoca de la següent manera:
result = rc.action.datastore_info( id="dca1d19c-bee5-4d2d-aae2-8ba2f92ddd07" )
El resultat que retorna és un diccionari amb:
- meta: diccionari de metadades del recurs amb, per exemple les files. Ex. {'id': 'dca1d19c-bee5-4d2d-aae2-8ba2f92ddd07', 'count': 2331, 'table_type': 'BASE TABLE', 'size': 1662976, 'db_size': 51872705883, 'idx_size': 499712, 'aliases': []}
- fields: llista dels camps amb l’identificador (id), el tipus de dada (type) i l’etiquetes (info.label). Ex. {'id': 'id_estacio', 'type': 'varchar', 'info': {'label': 'Id de l’estació'}
Aquestes són les 2 funcionalitats bàsiques de consulta de datasets a través de CKAN.
Tota la documentació oficial de CKAN la podeu trobar en aquest enllaç: https://docs.ckan.org/en/latest/maintaining/datastore.html#api-reference