API Tutorial

Questa guida mostra come interagire con ogni endpoint REST dell'API di Etna utilizzando curl o la libreria requests di Python.

Autenticazione

Tutti gli endpoint, ad eccezione di /privacy e /openapi.json, richiedono l'autenticazione tramite la tua chiave API. Sostituisci BASE_URL con l'indirizzo del tuo deployment (es. https://etna.tuodominio.com) e API_KEY con il valore impostato in ETNA_API_KEY.

Impostazioni Iniziali

bashBASE_URL=https://etna.tuodominio.com
API_KEY=la-tua-chiave-segreta

Metodi di Autenticazione

Puoi usare un header Bearer token o l'autenticazione HTTP Basic.

Bearer Token:

httpAuthorization: Bearer $API_KEY

HTTP Basic Auth:

bashcurl -u $API_KEY: "$BASE_URL/api/v1/events"

Endpoints API

Get Events

Recupera gli eventi registrati, filtrabili secondo vari criteri.

bash# Con Bearer token
curl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/events?limit=5"

# Con Basic auth
curl -u $API_KEY: \
  "$BASE_URL/api/v1/events?limit=5"

pythonimport requests

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"limit": 5}
res = requests.get(
    f"{BASE_URL}/api/v1/events", 
    headers=headers, 
    params=params
)
print(res.json())

Station Activity

Classifica l'attività delle stazioni in base al valore RMS medio delle ultime hours ore.

bashcurl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/stations/activity?hours=24"

pythonparams = {"hours": 24}
res = requests.get(
    f"{BASE_URL}/api/v1/stations/activity",
    headers=headers,
    params=params
)
print(res.json())

Station RMS Time Series

Restituisce la serie temporale dei valori RMS per le stazioni selezionate.

bashcurl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/stations/rms?station_codes=ECPN&hours=48"

pythonparams = {"station_codes": ["ECPN"], "hours": 48}
res = requests.get(
    f"{BASE_URL}/api/v1/stations/rms",
    headers=headers,
    params=params
)
print(res.json())

Station Polarization

Fornisce il back-azimuth rappresentativo orario per ogni stazione.

bashcurl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/stations/polarization?hours=12"

pythonparams = {"hours": 12}
res = requests.get(
    f"{BASE_URL}/api/v1/stations/polarization",
    headers=headers,
    params=params
)
print(res.json())

Station SSAM Analysis

Esegue l'analisi SSAM per le stazioni e le bande di frequenza selezionate.

bashcurl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/stations/ssam?station_codes=ECPN&bands=2-4"

pythonparams = {"station_codes": ["ECPN"], "bands": ["2-4"]}
res = requests.get(
    f"{BASE_URL}/api/v1/stations/ssam",
    headers=headers,
    params=params
)
print(res.json())

Correlations

Restituisce la matrice di correlazione tra RMS, Infrasuoni e Gas per una data finestra temporale.

bashcurl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/correlations?start_date=2024-01-01T00:00:00Z&end_date=2024-01-07T00:00:00Z"

pythonparams = {
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-07T00:00:00Z",
}
res = requests.get(
    f"{BASE_URL}/api/v1/correlations",
    headers=headers,
    params=params
)
print(res.json())

Bulletins

Elenca i bollettini disponibili o scarica un singolo PDF tramite il suo ID.

bash# Elenca gli ultimi 10 bollettini
curl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/bulletins?limit=10"

# Scarica un bollettino specifico
curl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/bulletins?id=0" --output bollettino.pdf

python# Elenca bollettini
params = {"limit": 10}
res = requests.get(
    f"{BASE_URL}/api/v1/bulletins",
    headers=headers,
    params=params
)
print(res.json())

Anomaly Detection

Rileva anomalie nei dati di una stazione utilizzando l'autoencoder LSTM.

bashcurl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"station": "ECPN", "threshold": 0.5}' \
  "$BASE_URL/api/v1/anomalies/detect"

pythonpayload = {"station": "ECPN", "threshold": 0.5}
res = requests.post(
    f"{BASE_URL}/api/v1/anomalies/detect",
    headers=headers,
    json=payload
)
print(res.json())

Privacy Policy

Recupera la privacy policy del servizio (non richiede autenticazione).

bashcurl "$BASE_URL/privacy"

pythonres = requests.get(f"{BASE_URL}/privacy")
print(res.json())