Questa sezione è rivolta a coloro che vogliono integrarsi con dati.emilia-romagna.it 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.emilia-romagna.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.emilia-romagna puoi ricercare dati oppure importare nel tuo portale tutti i dati di dati.emilia-romagna.
Per utilizzare le API di dati.emilia-romagna, 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 |
Stringp> |
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://lod.dati.emilia-romagna.it:8080/odapisrv/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:
["4","5","6","33","31","7","8","9","10","11","32","38","14","15","16"]
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://lod.dati.emilia-romagna.it:8080/odapisrv/api/rest/package/[id]
dove [Id] è l’identificativo di uno specifico Package.
Esempio:
http://lod.dati.emilia-romagna.it:8080/odapisrv/api/rest/package/5
Output
Il metodo Rest Package Id restituisce in output un oggetto di tipo Package.
Esempio di risposta:
{"id":"5","name":"5","title":"Comuni Regionali","version":"","url":"http://dati.emilia-romagna.it/catalogodati/dato/5-5-comuni-regionali.html","resources":[{"id":"","url":"http://dati.emilia-romagna.it/media/rdp/comune/dati/Comuni_v2.zip","format":"altro","description":"","hash":"","package_id":"5"}],"author":"Regione Emilia Romagna - Giunta Regionale - Direzioni Generali - Organizzazione, Personale, Sistemi Informativi e Telematica","author_email":"","maintainer":"Regione Emilia Romagna - Giunta Regionale - Direzioni Generali - Organizzazione, Personale, Sistemi Informativi e Telematica","maintainer_email":"","license_id":"","license":"CC-BY","metadata_created":"2011-10-11T02:00:00+0200","tags":["Cartografia","Comuni"],"notes":"Comprende i territori comunali e ne qualifica le eventuali isole amministrative o le porzioni in contestazione.\nDefinisce la superficie di un comune.","extras":{"topic":"Info geografiche - informazione cartografica|Info geografiche - topografia","metadata_created":"2011-10-11T02:00:00+0200","hidden_field":"Info geografiche informazione cartografica Info geografiche topografia","package_modified":"0001-01-01T01:00:00+0100","tag":"Cartografia|Comuni","visualization_url":"http://geoportale.regione.emilia-romagna.it/it/catalogo/dati-cartografic...","url":"http://dati.emilia-romagna.it/catalogodati/dato/5-5-comuni-regionali.html","author":"Regione Emilia Romagna - Giunta Regionale - Direzioni Generali - Organizzazione, Personale, Sistemi Informativi e Telematica","title":"Comuni Regionali","package_created":"0001-01-01T01:00:00+0100","source":"BO","description":"Comprende i territori comunali e ne qualifica le eventuali isole amministrative o le porzioni in contestazione.\nDefinisce la superficie di un comune.","package_type":"Dato geografico","license_id":"CC-BY","package_id":"5","metadata_modified":"2012-03-02T01:00:00+0100","metadata_source_modified":"0001-01-01T01:00:00+0100","valid_to":"2030-11-01T01:00:00+0100"}}
Package Search
Consente di ricercare un elenco di identificativi di Package.
Input
Il metodo Package Search riceve in input una stringa così formata:
http://lod.dati.emilia-romagna.it:8080/odapisrv/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=strade |
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":4,"results":["99","102","103","100"]}
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://lod.dati.emilia-romagna.it:8080/odapisrv/api/tag_counts
Output
Il metodo Tag_Counts restituisce in output un elenco di tag seguiti dal numero di Package corrispondenti.
Esempio di risposta:
[["Cartografia",66],["Geologia",28],["Processi Geologici",19],["Agricoltura",15],["Geomorfologia",15],["Pedologia",15],["Bilancio",14],["Pianificazione agricola",13],["Dati di BIlancio",10]]