SVILUPPATORIQuesta 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. |
|
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]]
