API Ckan - aperTO

Guida per l'utilizzo delle API di CKAN

In questa pagina vengono mostrati alcuni esempi dei possibili utilizzi che si possono fare delle API di CKAN, disponibili per tutti coloro che intendono scrivere programmi che interagiscano con i dati del portale AperTO o che semplicemente vogliono estrapolare dataset relativi a quanto caricato sul sito.

Disponibile anche la guida ufficiale della CKAN API in lingua inglese.

Per poter effettuare una chiamata alle API di CKAN su AperTO è innanzitutto necessario aprire una nuova scheda nel proprio browser web e scrivere l’indirizzo http://aperto.comune.torino.it/api/3/action/ seguito dai comandi opportuni (ad esempio http://aperto.comune.torino.it/api/3/action/package_list); per ogni comando è spesso possibile specificare diversi parametri, antecedendo un ‘?’ al primo parametro e una ‘&’ prima di ogni parametro successivo (ad esempio http://aperto.comune.torino.it/api/3/action/package_search?q=&rows=1000).

Seguono alcuni esempi di comandi utilizzabili sul portale (le risposte vengono fornite in formato JSON).

Comando package_list: restituisce la lista dei nomi dei dataset del sito ( http://aperto.comune.torino.it/api/3/action/package_list).
Parametri:
- "limit" (valore intero - se specificato permette di spezzare la lista di dataset in pagine di al più n dataset), es: http://aperto.comune.torino.it/api/3/action/package_list?limit=6;
- "offset" (valore intero – se il parametro "limit" è stato specificato, questo parametro permette di indicare da che numero partire ad elencare i dataset), es: http://aperto.comune.torino.it/api/3/action/package_list?limit=6&offset=3.
Comando group_list: restituisce la lista dei nomi dei gruppi tematici dei dataset del sito (http://aperto.comune.torino.it/api/3/action/group_list).
Parametri:
- "order_by" (è possibile specificare il valore ‘name asc’ per ottenere un ordinamento per nome crescente, ‘name desc’ per ottenere il medesimo ordinamento in ordine decrescente, ‘package_count asc’ e ‘package_count desc’ per ordinare i risultati per numero di dataset contenuti rispettivamente crescente o decrescente), es: http://aperto.comune.torino.it/api/3/action/group_list?order_by=package_count%20asc ;
- "all_fields" (valore booleano – se valorizzato a "true" restituisce tutti i metadati relativi ad ogni gruppo, tra cui il numero di dataset contenuti), es: http://aperto.comune.torino.it/api/3/action/group_list?all_fields=true,
- È ovviamente possibile combinare i due parametri, ad esempio scrivendo: http://aperto.comune.torino.it/api/3/action/group_list?order_by=name%20asc&all_fields=true.
Comando tag_list: restituisce la lista di tutti i tag utilizzati per metadatare i dataset sul portale (http://aperto.comune.torino.it/api/3/action/tag_list):
Parametri:
- "query" (stringa – permette di cercare e restituire solo i tag che contengono la stringa specificata), es: http://aperto.comune.torino.it/api/3/action/tag_list?query=consiglio;
- "all_fields" (valore booleano – se valorizzato a "true" restituisce tutti i metadati relativi ad ogni tag), es: http://aperto.comune.torino.it/api/3/action/tag_list?all_fields=true;
- È ovviamente possibile combinare i due parametri, ad esempio scrivendo: http://aperto.comune.torino.it/api/3/action/tag_list?query=consiglio&all_fields=true.
Comando package_show: restituisce i metadati di un determinato dataset tramite il suo id.
Parametri:
- "id" – parametro obbligatorio (è necessario specificare l’id alfanumerico del dataset, reperibile nella tabella "Informazioni supplementari" presente nella pagina di ogni risorsa – ad esempio questa http://aperto.comune.torino.it/dataset/servizio-di-refezione-scolastica-2018/resource/b043ff37-f75e-4d6f-9ba3-09b518773100#. È inoltre possibile specificare, al posto dell’id alfanumerico, il titolo del dataset così come mostrato nella URL. Ad esempio se si intendono visualizzare i metadati del dataset http://aperto.comune.torino.it/dataset/servizio-di-ristorazione-scolastica-2018 sarà sufficiente usare come id "servizio-di-ristorazione-scolastica-2018"). Esempi:
  - http://aperto.comune.torino.it/api/3/action/package_show?id=farmacie,
  - http://aperto.comune.torino.it/api/3/action/package_show?id=servizio-di-ristorazione-scolastica-2018,
  - http://aperto.comune.torino.it/api/3/action/package_show?id=b043ff37-f75e-4d6f-9ba3-09b518773100
Comando package_search: restituisce una lista di dataset, comprensivi di metadati, fornendo come input di ricerca una stringa.
Parametri:
- "q": parametro obbligatorio (stringa - mostra tutti i dataset che contengono la stringa specificata, sia nel titolo, che nella descrizione, che nei metadati - es. nei tag - ma NON all’interno del dataset stesso), es: http://aperto.comune.torino.it/api/3/action/package_search?q=metropolitana (mostra tutti i dataset che contengono la parola "metropolitana"). È possibile non specificare alcuna stringa come valore del parametro per farsi restituire la lista completa di dataset pubblicati sul portale (di default ne vengono mostrati 9, ma è possibile espandere la lista tramite i parametri indicati più avanti), es: http://aperto.comune.torino.it/api/3/action/package_search?q=
- "rows" (intero – permette di specificare quanti dataset mostrare per pagina, il valore massimo è 1000), es: http://aperto.comune.torino.it/api/3/action/package_search?q=&rows=1000
- "start" (intero - funziona come il parametro "offset" del comando "package_list", indicando da che numero partire ad elencare i dataset), es: http://aperto.comune.torino.it/api/3/action/package_search?q=&rows=1000&start=1000 (mostra tutti i dataset a partire dal numero 1000 – massimo 1000 per pagina).
  
  Se si volessero quindi ottenere tutti i dataset comprensivi di metadati presenti sul portale, nel caso in cui questi fossero più di 1000, occorrerebbe quindi eseguire più query, salvando i risultati e unendoli in un secondo momento:
  - http://aperto.comune.torino.it/api/3/action/package_search?q=&rows=1000 per ottenere i dataset da 0 a 999;
  - http://aperto.comune.torino.it/api/3/action/package_search?q=&rows=1000&start=1000 per ottenere i dataset da 1000 a 1999 (chiaramente la numerazione terminerà con l’ultimo dataset disponibile);