Servizi esposti agli utenti

I servizi esposti agli utenti ritenuti fondamentali sono: lo scaricamento dei tweet, lo scaricamento e la classificazione dei tweet e la verifica della presenza di un evento critico per la viabilità tramite i tweet. Tali servizi sono elencati nelle tabelle di seguito. Il web service che espone tali servizi è disponibile tramite il relativo WSDL (Web Service Description Language) all'indirizzo:

http://131.114.58.252:8080/ SmartyWeb/ SmartyTwitterServices?wsdl

scaricaTweet

Nome del Servizio

scaricaTweet

Descrizione

Si collega al data base di Twitter e scarica i tweet che corrispondono ai parametri specificati. Restituisce la lista dei tweet scaricati.

I parametri di ricerca specificabili dall'utente sono: geoCoordinate, raggio e data.

Nella versione attuale del servizio, che si concentra sull'identificazione di eventi di traffico, le ricerche su Twitter vengono fatte usando delle parole chiavi (non specificabili per il momento dall'interfaccia del servizio) che consentono di pre- fltrare i tweet di maggiore interesse. Le parole chiave sono: Traffico, Incidente, Code/a e #Traffico, #Incidente, #Coda/e.

Il parametro geoCoordinate consente di specificare un indirizzo testuale secondo le specifiche della GoogleMapsApi oppure una coppia di valori latitudine/longitudine definiti secondo lo

Via Diotisalvi 1, Pisa.

Via Diotisalvi 1, Pisa 56121, Italia. Pisa, Italia.

Via Diotisalvi 1, Italia (in questo caso non è detto che venga presa via Diotisalvi 1 di Pisa. Consultare la API per tutte le varie possibilità)

43.72913/10.38856 (Latitudine/Longitudine di “Pisa, Via Diotisalvi 1”)Per il corretto funzionamento del servizio, quando si fornisce la coppia latitudine/longitudine si raccomanda di separare i due valori senza spazi e tramite l'uso dello slash “/”.

Il raggio specifica l'estensione in chilomentri del raggio di ricerca, a partire dalla posizione specificata nel primo parametro.

Il parametro data consente di specificare la data e l'ora a partire dalla quale andare ad effettuare la ricerca dei tweet. Per un corretto scaricamento da Twitter è necessario che il timestamp della richiesta si trovi all'interno di un intervallo valido. In caso contrario viene utilizzato di default il timestamp 2014-01- 01T00:00:00. Consultare i tipi di errori (paragrafo “Codici di Errore”) per maggiori dettagli. Per un corretto funzionamento è necessario che i parametri relativi al timestamp siamo formattati secondo lo specifico standard ISO 80601. Il formato del timestamp utilizzato nel servizio è “YYYY-MM-DDTHH:MM:SS”. Gli offset relativi al timezone non vengono presi in considerazione.

In sintesi, il servizio consente di scaricare tutti i tweet che corrispondono ai parametri di ricerca a partire dalla data e ora specificata fino all'istante di chiamata del servizio.

Parametri

Nome Tipo Descrizione

geoCoordinate String L'indirizzo da cui effettuare la ricerca. Espresso o in formato testuale (via, numero, città, cap, nazione) o secondo lo standard DDD (latitudine/longitudine)

raggio Integer Definisce l'estensione in Km del

raggio da cui effettuare la ricerca. Se null viene usato di default un raggio di 15Km.

data String Timestamp che definisce la data e

l'ora a partire dai quali a scaricare i tweet. Deve rispettare lo standard ISO8601.

Valore Restituito Tipo Descrizione

String una stringa formattata in JSON che specifica l'esito dell'operazione e i risultati ottenuti. Il payload contiene la lista dei tweet corrispondenti ai parametri di ricerca, ovvero una lista di oggetti S UM (per maggiori informazione fare riferimento al capitolo “Oggetti Restituiti”) serializzati in formato JSON.

Esempio di Oggetto restituito

return (string): {"header": {"code":"200", "shortDescription":"OK", "longDescription":""}, "payload":[ {“type”: “SUM”, "id":20924, "idUtenteTwitter":"451671694365564928", "data":"2014-04-03 12:44:58.0",

"testo":"MARINA DI PISA – Domenica 3 aprile a Marina di Pisa l e strade lungo il mare si riempiranno dei banchi di un... http://t.co/ 92EEJJLJRv",

"lat/long":”null/null”}, {“type”: “SUM”,

"id":20925,"idUtenteTwitter":"451656339333595136", "data":"2014-04-03 11:43:57.0",

"testo":"RT @iltirreno: #Pisa, manifestazione degli artigiani: in tilt i l traffico sui lungarni #diamounascossa http://t.co/W9rL3LCU61", "lat/long":”null/null”},

{“type”: “SUM”, "id":20926,

"idUtenteTwitter":"451647470397693952", "data":"2014-04-03 11:08:42.0",

"testo":"Caschi gialli in corteo sui lungarni, traffico paralizzato: \"4 0 minuti di ritardo a lavoro\": E\u0027... http://t.co/uwZr5UHdkV v ia @PisaToday", "lat/long":”null/null”}, {“type”: “SUM” "id":20934, "idUtenteTwitter":"451627444647526401", "data":"2014-04-03 09:49:08.0",

"testo":"#Pisa. #Diamociunascossa. La testa del corteo è sul ponte S olferino e l

a coda in lungarno Galilei.", "lat/long":”41.7951931/12.2543841”, }] }

Id, data e testo sono attributi autoesplicativi, idUtenteTwitter contiene l'id dell'utente Twitter in

relazione al giorno e al tweet postato. lat/long contiene le coordinate in formato DDD se la geo-localizzazione del SUM è attiva, null altrimenti.

scaricaEclassificaTweet

Nome del Servizio

scaricaEclassificaTweet

Descrizione

Scarica una lista di tweet come nel servizio scaricaTweet e li classifica. Restituisce la lista dei tweet a ciascuno dei quali viene associato una etichetta (classe). Per quanto riguarda lo scaricamento, esso avviene secondo le stesse modalità ed utilizzando gli stessi parametri del servizio scaricaTweet. Per quanto riguarda la classificazione, il tweet viene etichettato utilizzando tutti i modelli di classificazione presenti nel sistema. All'interno del sistema viene gestito un database di modelli (modulo data mining) e un modello di classificazione è associato ad un evento specifico. Attualmente, viene utilizzato solamente il modello basato sulle Support Vector Machines SMO(citare) addestrato per riconoscere l'evento “Traffico”. Nello specifico, se nel testo del tweet vengono riconosciute informazioni relative alla presenza di traffico allora si classifica il tweet come interessante per l'evento “Traffico”.

Parametri

Nome Tipo Descrizione

geoCoordinate String L'indirizzo da cui effettuare la ricerca. Espresso o in formato testuale (via, numero, città, cap, nazione) o secondo lo standard DDD (latitudine/longitudine)

raggio Integer Definisce l'estensione in Km del

raggio da cui effettuare la ricerca. Se null viene usato di default un raggio di 15Km.

data String Timestamp che definisce la data e l'ora a partire dai quali a scaricare i tweet. Deve rispettare lo standard ISO8601.

Valore Restituito Tipo Descrizione

String una stringa formattata in JSON che specifica l'esito dell'operazione e i risultati ottenuti. Il payload contiene la lista dei tweet corrispondenti ai parametri di ricerca opportunamente classificati, nei quali viene fornita anche la geo-localizzazione del SUM qualora questa fosse attiva. Ogni tweet è seguito dalla lista di

SUMClassificato (per maggiori informazione fare

riferimento al capitolo “Oggetti Restituiti”) serializzati in formato JSON. La lista è formata da un oggetto SUMClassificato per ogni modello di classificazione presente nel sistema.

Esempio Oggetto Restituito

return (string): {"header": {"code":"200", "shortDescription":"OK", "longDescription":""}, "payload":[ {“type”: “SUM”, "id":26106, "idUtenteTwitter":"451747414022836225", "data":"2014-04-03 17:45:51.0",

"testo":"#A7 Traffico in congestione da Genova a Allacciamento A10 Genova-Ventimiglia.Velocità rilevata:15km/h",

"latlong":"null/null"}, {“type”: “SUMClassificato”, "id":957, "nomeEvento":"traffico", "valore":true, "nomeModelloUsato":"SMOTraffico.model", "latlong":"null/null"}, {“type”: “SUM”, "id":26107, "idUtenteTwitter":"451746656787378176", "data":"2014-04-03 17:42:50.0",

"testo":"Dobbiamo dire basta questo traffico di droga nelle scuole!!!",

"latlong":"41.8555744/12.564595"}, {“type”: “SUMClassificato”, "id":958, "nomeEvento":"traffico", "valore":false, "nomeModelloUsato":"SMOTraffico.model", "latlong":"null/null"},

In questo esempio si hanno due tweet seguiti dalla loro classifcazione effettuata con il modello SMOTraffico.model. I campi del payload relativi al S UM sono gli stessi del servizio scaricaTweet.

I campi del SUMClassificato id, geoIndirizzo, latlong, nomeModelloUsato sono di facile interpretazione. NomeEvento specifica l'evento su cui è stata effettuata la classificazione, valore specifica se il tweet è stato classificato come interessante per l'individuazione dell'evento nel tweet (true) o non interessante (false).

controllaEventi

Nome del Servizio

controllaEventi

Descrizione

Scarica e classifica i tweet con tutti i modelli di classificazione presenti nel sistema. Il servizio restituisce la lista degli eventuali eventi identificati. Per quanto riguarda la ricerca e lo scaricamento, esso avviene secondo le stesse modalità ed utilizzando gli stessi parametri del servizio scaricaTweet. Tutti i tweet scaricati vengono classificati utilizzando i modelli di classificazione presenti. Successivamente, viene applicata una politica di fusione di pareri che ha l'obiettivo di stabilire se un evento può essere effettivamente riconosciuto in una

determinata zona. A differenza del servizio

scaricaEclassificaTweet, questo servizio non si concentra solo sulla classificazione dei singoli tweet ma anche sull'interpretazione del risultato della classificazione su gruppi di tweet.

La politica di classificazione di eventi utilizzata nella versione attuale del servizio è la seguente:”se almeno il 20% dei tweet scaricati viene classificato come interessante per uno specifico evento, allora l'evento viene aggiunto al payload dell'oggetto

restituito”.

Parametri

Nome Tipo Descrizione

geoCoordinate String L'indirizzo da cui effettuare la ricerca. Espresso o in formato testuale (via, numero, città, cap, nazione) o secondo lo standard DDD (latitudine/longitudine)

raggio Integer Definisce l'estensione in Km del

raggio da cui effettuare la ricerca. Se null viene usato di default un raggio di 15Km.

data String Timestamp che definisce la data e

l'ora a partire dai quali a scaricare i tweets. Deve rispettare lo standard ISO8601.

visualizzaLog Boolean Se specificato a true, il servizio

restituisce anche la lista di tutti i tweet che l'hanno generato gli eventi identificati. Il valore di tale parametro è fissato a false di default.

Valore di ritorno Tipo Descrizione

String una stringa formattata in JSON che specifica l'esito dell'operazione e i risultati ottenuti. Il payload contiene una lista di oggetti EventoClassificato.(Uno per ogni evento identificato). Se il campo visualizzaLog assume valore true, allora ogni evento è restituito assieme alla lista dei tweet che lo hanno generato.

return (string): {"header": {"code":"200", "shortDescription":"OK", "longDescription":""}, "payload":[ {“type”: “EventoClassificato” "id":28, "nomeEvento":"traffico",

"dettagli":"Verifica la presenza di traffico nei Sum", "verificato":true,

"data":"2014-04-03 18:30:34",

"nomeModello":"SMOTraffico.model",

"geoIndirizzo":"Galleria Circonvallazione Settentrionale, 00166 Rome, Italy"} } {“type”: “SUM”

"id":26175,

"idUtenteTwitter":"451725490710384640", "data":"2014-04-03 16:18:44.0",

"testo":"Fila chilometrica all\u0027accettazione bagagli di @aegeanairlines all\u0027aeroporto di #Roma Fiumicino...in coda da un\u0027ora...", "latlong":"41.7951931/12.2543841"}, {“type”: “SUM” "id":26176, "idUtenteTwitter":"451725447718793216", "data":"2014-04-03 16:18:34.0",

"testo":"#A1 Traffico in congestione da Chiusi-Chianciano a Montepulciano.Velocità rilevata:35km/h", "latlong":"null/null"}, {“type”: “SUM” "id":26177, "idUtenteTwitter":"451724690244272128", "data":"2014-04-03 16:15:33.0",

"testo":"#SS7 Traffico in congestione da Innesto Ss374 Di Summonte E Montevergine a Montesarchio.Velocità rilevata:20km/h",

"latlong":"null/null"},

(VisualizzaLog = false)

return (string): {"header": {"code":"200",

"shortDescription":"OK", "longDescription":""},

"payload":[

{“type”:”EventoClassificato "id":28,

"nomeEvento":"traffico",

"dettagli":"Verifica la presenza di traffico nei Sum", "verificato":true,

"data":"2014-04-03 18:30:34"

"nomeModello":"SMOTraffico.model",

"geoIndirizzo":"Galleria Circonvallazione Settentrionale, 00166 Rome, Italy"}

] }

I campi del payload relativi al S UM sono gli stessi del

servizio scaricaTweet. I campi relativi

all'EventoClassificato sono: id, nomeEvento, dettagli, data e nomeModello, che sono autoesplicativi e di facile intuizione. GeoIndirizzo contiene nella versione attuale del servizio l'indirizzo dal quale è stata effettuata la ricerca.