Questa sezione è rivolta a coloro che vogliono integrarsi con dati.piemonte utilizzando le API messe a disposizione dal portale, realizzate in modo conforme al modello CKAN, assunto come standard di comunicazione tra portali.

Le API del portale dati.piemonte.it sono conformi al modello CKAN, e garantiscono la comunicazione con la piattaforma di ricerca Solr del progetto Apache Lucene, utilizzato dal portale.

Mediante le API di dati.piemonte puoi ricercare dati oppure importare nel tuo portale tutti i dati di dati.piemonte.

Per utilizzare le API di dati.piemonte, la tua applicazione deve effettuare una richiesta HTTP e parsificare la risposta, che di default è in formato JSON.

STRUTTURA DEGLI OGGETTI

Package-List
Il Package-List contiene un elenco di identificativi di Package, che si riferiscono ad oggetti di tipo Package.


Formato:

[Id_1, Id_2, Id_3, ... ,Id_n]

Id_n indica l'identificativo del Package n ed è una stringa.

Package
Il Package è l'oggetto principale di tutto il sistema; esso rappresenta il metadato, ossia il set di informazioni che descrivono il dato.

Formato:
{ id: id, name: name, title: title, version: version, url: url, resources: [ Resource1, Resource2, ...], author: author, author_email: author_email, maintainer: maintainer, maintainer_email: maintainer_email, license_id: license_id, tags: Tag-List, notes: notes, extras: { Name: Value, ... } }

Nella tabella sottostante sono riportati i dettagli dei vari attributi.
 

Attributi dell'oggetto

Nome attributo

Tipo attributo

Note

id

String

Identificativo del package

name

String

Identificativo del package interno al portale riuso

title

String

Titolo del package

version

String

Versione del package

url

String

Url della pagina web in cui sono descritti i metadati del package

resources

Resource

Elenco di oggetti di tipo Resource collegati al package

author

String

Proprietario del package

author_email

String

Riferimento email del proprietario del package

maintainer

String

Gestore o responsabile della pubblicazione del package

maintainer_email

String

Riferimento email del gestore o responsabile della pubblicazione del package

license_id

String

Identificativo della licenza a cui è assoggettato l'utilizzo del package (ad esempio “cc-by”)

tags

Tag-List

Oggetto di tipo Tag-List.
Contiene i name dei Tag associati al package

notes

String

Ulteriori informazioni sul package

extras

String

Attributi aggiuntivi del package, costituiti da un elenco di coppie Name: Value, dove Name è il nome dell'attributo e Value il valore corrispondente. Il numero delle coppie non ha un limite massimo.


Tag-List
Il Tag-List rappresenta un elenco di Tag, con indicazione del numero di Package relazionati con ciascuno di essi.

Formato:
[ [ “name”, n], [“name”, n], …...., [“name”, n] ]

dove “Name” indica il Name del Tag e “n” indica il numero di Package relazionati con il Name.

Tag
Un Tag rappresenta una parola chiave ed ha significato se riferita ad un Package. Un Package può essere relazionato a più Tag.

Formato:
{ name: name }

Nella tabella sottostante sono riportati i dettagli dei vari attributi.
 

Attributi dell'oggetto

Nome attributo

Tipo attributo

Note

name

String

Nome del tag


Resource
L'oggetto Resource contiene le informazioni per raggiungere il dato vero e proprio, descritto attraverso il Package. Il Resource corrisponde ad un file o ad un'altra risorsa di dati disponibile on line.
Un Resource è sempre collegato ad un Package (o Dataset), che può avere più Resources associati.

Formato:
{ url: url, format: format, description: description, hash: hash }

Nella tabella sottostante sono riportati i dettagli dei vari attributi.
 

Attributi dell'oggetto

Nome attributo

Tipo attributo

Note

id

String

Identificativo del Resource

url

String

Url che consente di raggiungere la location in cui la risorsa è effettivamente disponibile.

format

String

Formato della risorsa (ad esempio zip, csv, ecc.).

description

String

Descrizione della risorsa

hash

String

Hash

package_id

String

Identificativo del Package a cui il Resource si riferisce


METODI DI RICERCA

Rest Package
Consente di estrarre l'elenco degli identificativi di tutti i Package presenti nel repository.

Input
Il metodo Rest Package viene chiamato mediante una stringa così formata:

http://www.dati.piemonte.it/rpapisrv/api/rest/package

Output
Il metodo Rest Package restituisce in output un oggetto di tipo Package-List, ossia un elenco di identificativi di Package.

Esempio di risposta:

["1153", "1083", "1231", "1075", "1074", "1176", "1173", "1215", "1226"]

Rest Package Id
Consente di estrarre le informazioni complete di un Package relativo ad uno specifico identificativo.

Input
Il metodo Rest Package Id viene chiamato mediante una stringa così formata:

http://www.dati.piemonte.it/rpapisrv/api/rest/package/[id]

dove [Id] è l’identificativo di uno specifico Package.

Esempio:

http://www.dati.piemonte.it/rpapisrv/api/rest/package/1153

Output
Il metodo Rest Package Id restituisce in output un oggetto di tipo Package.

Esempio di risposta:

{"id":"dati-piemonte-it-package-1153","name":"1153","title":"Reticolo idrografico regionale - DB Prior 10K- Elementi idrici","version":"","url":"http://www.dati.piemonte.it/dato/item/1153-reticolo-idrografico-regionale-db-prior-10k-elementi-idrici.html","resources":[{"id":"","url":"http://gis.csi.it/repertorio/sitad_wgs84/
DBPR10_ELEMIDRI/elemidri.zip","format":"SHP","description":"","hash":"","package_id":"dati-piemonte-it-package-1153"}],"author":"805","author_email":"","maintainer":"","maintainer_email":"","license_id":"CC0","tags":[],"notes":"","extras":[]}

Package Search
Consente di ricercare un elenco di identificativi di Package.

Input
Il metodo Package Search riceve in input una stringa così formata:

http://www.dati.piemonte.it/rpapisrv/api/search/package?q=[tag]

seguita da una serie di coppie Chiave:Valore.

La struttura della chiamata è conforme alla struttura prevista dal motore Solr/Lucene, supportato da CKAN a partire dalla versione 1.5.

Nella tabella che segue sono elencati i parametri da utilizzare.

Chiave

Valore

Esempio

Note

q

Stringa di ricerca

q=piemonte

Questa stringa viene ricercata all'interno di tutti i campi dell'oggetto Package.

Output
La risposta al metodo Package Search è strutturata nel seguente modo:

{ “count”: Count-int, “results”:[Id_Package, Id_Package, …] }

dove Count-int è il numero di Packages estratti e Id_Package è l'identificativo del Package.

Esempio di risposta:

{"count": 6, "results": ["dati-piemonte-it-package-100130", "dati-piemonte-it-package-1079", "dati-piemonte-it-package-1367", "dati-piemonte-it-package-100157", "dati-piemonte-it-package-1196", "dati-piemonte-it-package-1356"]}

Tag Counts
Il metodo Tag_Counts consente di estrarre l'elenco dei tag con indicazione del numero di Packages relazionati con ciascuno di essi.

Input
Il metodo Tag_Counts viene chiamato mediante una stringa così formata:

http://www.dati.piemonte.it/rpapisrv/api/tag_counts

Output
Il metodo Tag_Counts restituisce in output un elenco di tag seguiti dal numero di Package corrispondenti.

Esempio di risposta:

[["Carburante":2], ["Scuola":10], ["Bevande":3], ["Impianti":8], ["Finanziamenti":2], ["Agricoltura":19], ["Foreste":2], ["Infanzia":3], ["copertura":3], ["Farmacie":2], ["Rivendita":15], ["Addetti":3]]


Tranne per i materiali specificatamente ed espressamente indicati come diversamente tutelati , i contenuti del sito sono soggetti alla licenza Creative Commons Attribution CC BY 2.5