Terremoti REST API

Open Source REST API per informazioni sui terremoti

Progetto sviluppato per sostenere l'esame di Programmazione ad Oggetti (Università Politecnica delle Marche, anno accademico 2020/2021)

Descrizione

Questa REST API permette di ottenere le informazioni sui terremoti registrati dalla Rete Sismica Nazionale negli ultimi sette giorni.

I dati sono ricavati dai tweet postati dall'account Twitter dell'Istituto Nazionale di Geofisica e Vulcanologia (@INGVterremoti).

Sommario

• Utilizzo
• Rotte
• Formato dei dati
• Esempi
• Filtri
• Compilazione
• Configurazione
• Diagramma dei casi d'uso
• Diagramma delle classi
• Credits

Utilizzo

Per usufruire dell'API è necessario fare delle richieste GET o POST all'url http://localhost:8000 specificando la rotta e il body della richiesta a seconda dei dati che si vuole ricevere.

Rotte

Tipo	Rotta	Descrizione
GET	/	Restituisce le informazioni sui terremoti
GET	/stats	Restituisce la media di terremoti al giorno
GET	/stats?field=<campo>	Restituisce le statistiche del campo specificato (i campi validi sono valoreMagnitudo e profondita)
GET	/metadata	Restituisce i metadati
POST	/	Restituisce le informazioni sui terremoti filtrati con le regole specificate nel body della richiesta (vedi la sezione Filtri)
POST	/stats	Restituisce la media di terremoti al giorno, calcolata solo con i terremoti filtrati con le regole specificate nel body della richiesta (vedi la sezione Filtri)
POST	/stats?field=<campo>	Restituisce le statistiche del campo specificato, calcolate solo con i terremoti filtrati con le regole specificate nel body della richiesta (i campi validi sono valoreMagnitudo e profondita)

Formato dei dati

I dati vengono sempre restituiti in formato JSON con i seguenti campi per le informazioni sui terremoti:

• valoreMagnitudo valore della magnitudo
• tipoMagnitudo tipo di magnitudo, locale (ML) o momento (Mw)
• ora ora a cui è avvenuto il terremoto in formato hh:mm
• data giorno in cui è avvenuto il terremoto in formato dd-MM-yyyy
• localita luogo in cui è avvenuto il terremoto
• profondita profondità alla quale è avvenuto il terremoto espressa in km
• link link da seguire per avere maggiori informazioni sul terremoto

e con i seguenti campi per le statistiche:

• avg valore medio del campo specificato
• max valore massimo del campo specificato
• min valore minimo del campo specificato
• mediaGiorno media dei terremoti avvenuti in un giorno

Esempi

GET http://localhost:8000 restituisce un JSON di questo tipo:

[
	{
		"valoreMagnitudo": 3.7,
		"tipoMagnitudo": "ML",
		"ora": "17:28",
		"data": "02-07-2020",
		"localita": "Costa Siracusana (Siracusa)",
		"profondita": 14.0,
		"link": "https://t.co/jN8Tgw5zir"
	},
	{
		"valoreMagnitudo": 2.8,
		"tipoMagnitudo": "ML",
		"ora": "21:24",
		"data": "30-06-2020",
		"localita": "2 km NW Lama Mocogno (MO)",
		"profondita": 18.0,
		"link": "https://t.co/Ni1DGcG62E"
	}
]

GET http://localhost:8000/stats restituisce un JSON di questo tipo:

{
	"mediaGiorno": 1.6666666,
}

GET http://localhost:8000/stats?field=valoreMagnitudo restituisce un JSON di questo tipo:

{
    "min": 2.5,
    "avg": 3.2916667,
    "max": 6.3
}

Filtri

Quando si esegue una richiesta POST all'API è possibile specificare nel body le regole in formato JSON in base alle quali verranno filtrati i risultati.

Il filtro ha il seguente formato:

{
    "<operatore>": [
        {
            "<operatore>": [
                {
                    "var": <campo>
                },
                <valore>
            ]
        },
        ...
    ]
}

il seguente esempio filtra i terremoti che hanno un valore di magnitudo minore di 3 e sono avvenuti a una profondità maggiore di 10 km:

{
    "and": [
        {
            "<": [
                {
                    "var": "valoreMagnitudo"
                },
                3
            ]
        },
        {
            ">": [
                {
                    "var": "profondita"
                },
                10
            ]
        }
    ]
}

il seguente esempio filtra i terremoti che sono avvenuti dal 2 luglio 2020:

{
    ">=": [
        {
            "var": "data"
        },
        20200702
    ]
}

Lista degli operatori

Operatori condizionali:

• > maggiore di (solo per i campi valoreMagnitudo, profondita, data in formato yyyyMMdd)
• < minore di (solo per i campi valoreMagnitudo, profondita, data in formato yyyyMMdd)
• >= maggiore o uguale di (solo per i campi valoreMagnitudo, profondita, data in formato yyyyMMdd)
• <= minore o uguale di (solo per i campi valoreMagnitudo, profondita, data in formato yyyyMMdd)
• == uguale a

Operatori logici:

• and
• or

Compilazione

Per compilare l'applicazione è necessario avere il Java Development Kit 11 e Maven installati ed eseguire i seguenti comandi da terminale:

git clone https://github.com/mrgian/terremoti-api.git

cd progetto-oop

mvn clean package

se la build va a buon fine dovresti ricevere un avviso di questo tipo:

[INFO] BUILD SUCCESS

e troverai il l'eseguibile nella directory target con il nome terremoti-api-1.0.jar

Per eseguire l'applicazione basta eseguire il comando java -jar terremoti-api-1.0.jar

Configurazione

É possibile modificare la configurazione di default modificando i dati presenti nel file JSON src/main/resources/defaultConfig.json, dove:

• baseUrl è url dell'API da interrogare per ricavare i dati (senza parametri)
• token è il bearer token per l'autenticazione
• user è l'username dell'account Twitter da cui ricavare i dati

Diagramma dei casi d'uso

Diagramma delle classi

Credits

Progetto interamente sviluppato da Gianmatteo Palmieri