ckanapi cli¶

È un'utility per per utilizzare le API di CKAN.
CKAN è la piattaforma open source più usata per la realizzazione di portali open data: imparare a usare questo strumento è molto comodo, per interagire "a riga di comando" con tantissimi portali di questo tipo.

Installazione¶

Si installa rapidamente con

pip install ckanapi

oppure con

uv tool install ckanapi

Esempi di query¶

Le ricerche sono basate su solr, e per diversi campi non è una ricerca per stringa esatta (vedi nota).

Ricerca per stringa¶

Ad esempio la stringa furgoni, in qualsiasi campo:

ckanapi -r https://dati.gov.it/opendata/ action package_search q='furgoni'

Numero di risultati

Di default il numero di risultati presentati in un output di package_search è pari a 10. Per modificarlo bisogna introdurre il parametro rows (il valore massimo di default è pari a 1000).

Il numero di risultati di una ricerca per dataset¶

L'azione package_search restituisce sempre in output, il parametro count. Si può allora impostare a 0 il numero di record di output da visualizzare (perché non si vuole qui leggere i dettagli dei risultati) ed estrarre dall'output del JSON soltanto count:

ckanapi -r https://dati.gov.it/opendata/ action package_search q='scuole' rows=0 | jq '.count'

La risposta è immediata, perché non vengono listate le decine di dataset che contengono la stringa scuole, ma soltanto il conteggio degli stessi.

Ricerca per titolo¶

Tutti i dataset che hanno nel titolo la parola farmacie:

ckanapi -r https://dati.gov.it/opendata/ search datasets q='(title:"farmacie")'

Tutti i dataset che hanno nel titolo le parola farmacie e anno:

ckanapi -r https://dati.gov.it/opendata/ search datasets q='(title:"farmacie" title:"anno")'

Tutti i dataset che hanno nel titolo le parola farmacie o distributori:

ckanapi -r https://dati.gov.it/opendata/ search datasets q='(title:"farmacie" OR title:"distributori")'

Ricerca dataset basata su field extra¶

Nei dataset spesso ci sono diversi campi descrittivi, nell'array extras. Due di esempio:

{
  "key": "contact_email",
  "value": "dirigenteat@comune.copertino.le.it"
},
{
  "key": "contact_name",
  "value": "comune-di-copertino"
},
{
  "key": "identifier",
  "value": "c_c978:openpnrr-comune-di-copertino"
}

Per cercare tramite questi campi, si può usare il nome della key. Ad esempio:

ckanapi -r https://dati.gov.it/opendata/ action package_search fq='identifier:*pnrr*' rows=10

Carattere jolly

* è il carattere jolly per le ricerche. Ad esempio con identifier:*prova* si avranno tutti i risultati che hanno come identifier "approvate", ma anche "approvadibomba".

Ricerca per data di creazione dei metadati¶

ckanapi -r  https://dati.regione.sicilia.it action package_search fq='metadata_created:[2017-04-12T00:00:00Z TO 2022-06-30T23:59:05Z]' rows:1

Con rows:1 prendo soltanto il primo risultato.

Oppure (è preferibile perché è un output jsonl)

ckanapi -r  https://dati.regione.sicilia.it search datasets fq='metadata_created:[2017-04-12T00:00:00Z TO 2022-06-30T23:59:05Z]' rows:1

Ricerca dataset per formato delle risorse contenute¶

La ricerca di dataset per formato delle risorse contenute, dalla documentazione ufficiale non sembra possibile. È però possibile farlo, usando un parametro non documentato, di cui c'è traccia nella documentazione sulle viste: res_format.

Per avere restituito ad esempio i dataset che contengono almeno una risorsa in formato CSV, il comando è:

ckanapi -r https://dati.gov.it/opendata/ search datasets fq='(res_format:"CSV")' rows=1

È possibile ovviamente arricchire la query, aggiungendo al filtro per formato, quello per organizzazione:

ckanapi -r https://dati.gov.it/opendata/ search datasets fq='(res_format:"CSV" AND organization:"regione-toscana")' rows=1

Ad agosto del 2022, la cosa risulta ancora non documentata: https://github.com/ckan/ckan/discussions/7013.

Utilizzare più parametri di ricerca di un dataset e combinarli in AND¶

ckanapi search datasets -r https://dati.gov.it/opendata/ fq='(organization:"comune-di-torino" AND groups:"ambiente")' rows=1

Nota bene: rows=1 limita l'output a un solo risultato. Qui è inserito soltanto per testare la query.

Esempi di filtri¶

Tutti i dataset con 30 tag¶

ckanapi -r https://dati.gov.it/opendata/ search datasets fq='(num_tags:30)'

Tutti i dataset di un'organizzazione¶

ckanapi -r https://dati.toscana.it/ search datasets fq='(organization:"comune-di-firenze")' -O datasets.jsonl.gz -z

Note:

-O per definire il file di output. È un JSON Lines;
-z per avere l'output JSON Lines compresso in gzip.

Varie¶

Numero di dataset per organizzazione¶

ckanapi -r https://dati.toscana.it/ action package_search facet.field:'["organization"]' rows:0

Numero di dataset per un dato gruppo tematico¶

ckanapi -r https://dati.gov.it/opendata/ action package_search fq='(groups:"ambiente")' facet.field:'["organization"]' rows=0

Download dei risultati di una ricerca in loop¶

URL="https://mysample.url"
ckanapi -r "$URL" search datasets fq='(title:"taxes")' | \
jq -r '.id' | \
xargs -I _ ckanapi -r "$URL" dump datasets _ --datapackages=./out

Vedi https://github.com/ckan/ckanapi/issues/197#issuecomment-1069173069

Note sulle ricerche fatte su CKAN¶

Alcune delle ricerche fatte su CKAN, sfruttano come motore solr.
Di default, su solr, i campi su cui è possibile eseguire una ricerca sono impostati come type=text, e su questi non è attiva una ricerca "esatta", ma sempre una ricerca fuzzy.
Per la ricerca esatta i campi devono essere impostati come type=string.

Nello schema solr di CKAN è possibile leggere il type dei vari campi. Ad esempio res_format è impostato come string e su questo sarà possibile eseguire ricerche esatte.