🧠 OVERVIEW (introduzione API)

Drone Sky Check API permette di analizzare lo spazio aereo per operazioni con droni in una specifica posizione geografica.

A differenza di sistemi puramente statici, l’analisi non si basa solo su dati cartografici (ENR), ma integra più livelli informativi:

• Spazio aereo ufficiale (ENR / AIP)

• NOTAM attivi (restrizioni temporanee)

• Logica operativa per interpretazione del rischio

L’obiettivo non è solo fornire dati grezzi, ma restituire una valutazione utilizzabile direttamente in fase operativa, indicando:

• se il volo è consentito

• a quale quota

• eventuali criticità o restrizioni temporanee

Le API non sono deterministiche pure.

Il risultato è una sintesi operativa derivata da più fonti, con priorità diverse:

1. NOTAM attivi (priorità massima)

2. Restrizioni ENR

3. Regole base di volo

Questo significa che:

• una zona ENR aperta può diventare NO_FLY per un NOTAM

• una zona può risultare “LIMITED” anche se formalmente volabile

📍 zoneCheckV2

Questa è l’API principale per l’analisi di un punto.

Dato un punto geografico, restituisce:

• stato del volo (OPEN / LIMITED / NO_FLY)

• quota massima consentita

• distanza dalla zona sicura più vicina

• analisi dettagliata delle restrizioni presenti

🧾 PARAMETRI

• lat (number, obbligatorio)
  Latitudine del punto

• lon (number, obbligatorio)
  Longitudine del punto

• bearing (number, opzionale)
  Direzione di movimento (gradi).
  Usato per stimare l’uscita da una NFZ in modo più realistico.

📦 OUTPUT — SIGNIFICATO CAMPI

status

Indica lo stato operativo del volo:

• OPEN → volo consentito fino a 120m

• LIMITED → volo consentito con limitazioni (tipicamente quota)

• NO_FLY → volo non consentito

maxAltitude

Quota massima consentita in metri.

• 0 → divieto totale

• <120 → limitazione

• 120 → standard open

currentZone

Informazioni sulla zona principale in cui si trova il punto:

• nome zona

• tipo (ENR, NOTAM, ecc.)

Serve solo come riferimento, non è l’unica fonte della decisione finale.

nearestOpen

Zona più vicina in cui il volo è consentito.

Include:

• distanza

• limite di quota

Utile per suggerire dove spostarsi.

distanceToExitMeters

Distanza stimata per uscire da una zona NO_FLY.

• valorizzato solo se dentro NFZ

• può usare il bearing per essere più realistico

analysis

Spiega perché è stato deciso quello stato.

source

Indica da dove deriva la decisione finale:

• BASE → solo ENR

• NOTAM → presenza NOTAM determinante

blockers

Motivi che impediscono il volo.

Esempio:

• NOTAM attivo

• restrizione temporanea

warnings

Condizioni non bloccanti ma rilevanti.

Esempio:

• NOTAM “soft”

• ENR non attivo al momento

• incertezza temporale

zones

Lista di tutte le zone che intersecano il punto.

Per ciascuna zona:

• dati base (nome, tipo, limiti)

• analisi ENR

• analisi NOTAM

Questa parte serve per debug o per UI avanzate.

🧠 LOGICA DI RISOLUZIONE

Il risultato finale non è una semplice lettura di una zona, ma una risoluzione tra più condizioni.

Regole principali:

1. NOTAM HARD attivo → forza NO_FLY

2. NOTAM SOFT attivo → non blocca, ma genera warning

3. ENR inattivo → warning (potenziale non applicabilità)

4. fallback → viene usato lo stato base ENR

👉 In pratica:

• NOTAM può sovrascrivere completamente ENR

• ENR da solo non è sufficiente per decidere

🆕 Sezione enr.advanced

Questa sezione introduce una valutazione avanzata degli orari ENR, più realistica rispetto alla logica base.

👉 Serve per:

• interpretare condizioni complesse (giorni, tramonto, OR)

• debug e validazione

• future evoluzioni (senza rompere la compatibilità)

————————————————————

🔹advanced.hasAdvanced

"hasAdvanced": true

Significato

Indica se è stata effettuata una valutazione avanzata degli orari ENR.

Valori

• true → almeno una schedule è stata interpretata con logica avanzata

• false → nessuna interpretazione possibile (fallback base)

Nota

Non indica il risultato, ma solo la disponibilità del parsing avanzato.

————————————————————

🔹 advanced.evaluated[]

Array contenente il dettaglio della valutazione per ogni schedule trovata.

🔸 raw

"raw": "MON-FRI 0700-1800 O/OR 0700-SS+30 ..."

Testo originale degli orari ENR (come da AIP / dump).

🔸 normalized

"normalized": "MON-FRI 0700-1800 O/OR 0700-SS+30 ..."

Versione normalizzata della stringa:

• rimozione parentesi

• rimozione rumore

• uniformata per parsing

👉 utile per debug o logica frontend

🔸 basic

"basic": true

Risultato della logica semplificata (legacy).

• Usa solo pattern HHMM-HHMM

• Ignora giorni e tramonto
  

Valori

• true → zona attiva (non è possibile volare)

• false → non attivo (è possibile volare)

• null → non interpretabile

🔸 advanced

"advanced": false

Risultato della valutazione avanzata runtime.

Tiene conto di:

• giorno della settimana

• orari multipli

• condizioni OR (O/OR)

• tramonto (SS+offset)

• timezone locale (Europe/Rome)

Valori

• true → ENR attiva ora (non è possibile volare)

• false → ENR non attiva ora (è possibile volare)

• null → impossibile determinare

🆕 Valutazione orari ENR

L’API restituisce due diverse interpretazioni degli orari ENR:

• basic → valutazione semplificata (retrocompatibile)

• advanced → valutazione avanzata (più realistica)

Questi due valori sono indipendenti: l’API non sceglie quale usare, ma fornisce entrambe le informazioni.
È responsabilità del client decidere quale utilizzare.

🔹 basic

Valutazione semplice basata solo su intervalli orari nel formato:

HHMM-HHMM

Caratteristiche

• Non considera giorni della settimana

• Non considera condizioni come alba/tramonto

• Non interpreta logiche complesse (OR, AND, ecc.)

Quando usarlo

• Applicazioni semplici

• Compatibilità con versioni precedenti

• Approccio conservativo lato implementazione

————————————————————

🔹 advanced

Valutazione avanzata degli orari ENR basata su:

• giorno della settimana (es. MON-FRI)

• condizioni multiple (O/OR)

• condizioni astronomiche (SS+offset, tramonto)

• timezone locale (Europe/Rome)

Caratteristiche

• Più accurato rispetto a basic

• Basato su parsing runtime del testo ENR

• Può restituire null se non interpretabile

————————————————————

🔹 explanation

Quando si utilizza la modalità advanced è possibile utilizzare anche l'interpretazione "umana" della valutazione oraria

⚠️ Nota importante

Il campo advanced è più preciso ma si basa su parsing automatico di testo non strutturato.
In alcuni casi complessi potrebbe non essere completamente affidabile.

🟢 1. Approccio base (semplice)

if (basic === true) {
// Zona ENR attiva
} else {
// Zona ENR non attiva
}

👉 Pro:

• semplice

• stabile

👉 Contro:

• meno preciso (ignora tramonto, giorni, ecc.)

🟡 2. Approccio avanzato

if (advanced === true) {
// Zona ENR attiva
} else if (advanced === false) {
// Zona ENR non attiva
} else {
// fallback o gestione custom
}

👉 Pro:

• più realistico

• tiene conto delle condizioni reali

👉 Contro:

• può avere edge case non gestiti

🟠 3. Approccio conservativo (consigliato)

if (advanced !== null) {
if (advanced === true) {
// Zona ENR attiva
} else {
// Zona ENR non attiva
}
} else {
// fallback su basic
if (basic === true) {
// Zona ENR attiva
} else {
// Zona ENR non attiva
}
}

👉 Pro:

• combina precisione e robustezza

• fallback automatico

🧪 Esempi di utilizzo

⭕4. Utilizzo di explanation

"advanced": {

"evaluated": [

{

"raw": "1) FROM 1 SEP TO 30 JUN MON-FRI 0630-2200 (0530-2100); SAT ANNOUNCED BY NOTAM; HOL ESCLUSI/EXCLUDED.",

"normalized": "1) FROM 1 SEP TO 30 JUN MON-FRI 0630-2200",

"basic": true,

"advanced": false,

"explanation": "Zona NON attiva: fuori dalla fascia 06:30–22:00",

"window": {

"start": "06:30",

"end": "22:00"

}

}

],

"hasAdvanced": true

🔹 zoneCheckV2 — ESEMPIO CHIAMATA

📡 HTTP

curl -X GET "https://zonecheckv2-32dg4v266a-uc.a.run.app?lat=41.9361&lon=12.4312" \
-H "x-api-key: YOUR_API_KEY"

🔹 Variante con parametri opzionali

curl -X GET "https://zonecheckv2-32dg4v266a-uc.a.run.app?lat=41.9361&lon=12.4312&bearing=90" \
-H "x-api-key: YOUR_API_KEY"

🔹 zoneCheckV2 — ESEMPIO OUTPUT

❌ Caso: NO_FLY (NOTAM attivo)

{
"position": {
"lat": 41.9361,
"lon": 12.4312
},
"status": "NO_FLY",
"maxAltitude": 0,
"currentZone": {
"name": "NOTAM W0363/26",
"where": "NFZ/NOTAM"
},
"nearestOpen": {
"distanceMeters": 1850,
"zone": {
"name": "Area Open",
"limit": 120
}
},
"distanceToExitMeters": 320,
"analysis": {
"source": "NOTAM",
"blockers": [
{
"zone": "NOTAM W0363/26",
"reason": "ACTIVE_HARD_NOTAM",
"activity": "Drone flight restriction"
}
],
"warnings": []
}
}

🗺️ zones

API per recuperare le zone geografiche in formato GeoJSON.

Serve principalmente per:

• visualizzazione su mappa

• rendering layer (Leaflet, Mapbox, ecc.)

🧾 PARAMETRI

• bbox (obbligatorio)
  Bounding box nel formato:

  minLat,minLon,maxLat,maxLon

• simplify (opzionale)
  Riduce la complessità delle geometrie per migliorare le performance

• limit (opzionale)
  Numero massimo di zone restituite

• type (opzionale)
  Filtro per tipo di zona

• restriction (opzionale)
  Filtro per tipo di restrizione

📦 OUTPUT

Restituisce un GeoJSON standard:

• FeatureCollection

• lista di feature con:

  • geometria

  • proprietà (nome, tipo, limiti)

Pronto per essere utilizzato direttamente in librerie di mapping.

🔹 zones — ESEMPIO CHIAMATA

📡 HTTP

curl -X GET "https://zones-32dg4v266a-uc.a.run.app/zones?bbox=41.90,12.48,41.95,12.52" \
-H "x-api-key: YOUR_API_KEY"

🔹 zones — ESEMPIO OUTPUT

{

"type": "FeatureCollection",

"features": [

{

"type": "Feature",

"properties": {

"id": "T013104",

"name": "NOTAM W0363/26",

"type": "P_NOTAM",

"restriction": "PROHIBITED",

"lowerLimit": 0,

"upperLimit": 30

},

"geometry": {

"type": "Polygon",

"coordinates": [

[

[12.431247577301185,41.9361504799798],

[12.429739454659252,41.93744161942455],

[12.427749251658245,41.93658906519803],

[12.428798388144504,41.93484758517533],

[12.431247577301185,41.9361504799798]

]

]

}

},

⚠️ Disclaimer

Le API Drone Sky Check forniscono un supporto informativo per la valutazione operativa dello spazio aereo, ma non sostituiscono in alcun modo le fonti ufficiali aeronautiche né la responsabilità del pilota.

I dati restituiti derivano da più fonti (ENR, NOTAM, logiche interpretative) e possono essere soggetti a variazioni, aggiornamenti o limitazioni.

È responsabilità dell’operatore:

• verificare sempre le condizioni reali e aggiornate

• consultare le fonti ufficiali prima di effettuare qualsiasi operazione di volo

• operare nel rispetto della normativa vigente

  
  

🔐 Accesso alle API

L’accesso alle API è riservato.
Per richiedere una API Key, contattami tramite il form del sito indicando il progetto e l’utilizzo previsto.

🚦 Rate Limit

🔹 Limiti di utilizzo

Le API sono soggette a limitazioni per API Key, applicate su base temporale.

Limiti standard:

• 40 richieste al minuto per API Key

Limiti specifici per endpoint:

• endpoint contenenti lite → 120 richieste/minuto

• endpoint contenenti route → 10 richieste/minuto
  

🔹 Comportamento in caso di superamento

Se il limite viene superato:

• le richieste successive possono ricevere risposta:

  • 429 Too Many Requests

• l’accesso può essere temporaneamente limitato
  

🔹 Best practice

Si consiglia di:

• evitare polling troppo frequente

• utilizzare caching lato client quando possibile

• aggiornare i dati a intervalli ragionevoli (es. ogni 5–10 secondi)

  
  

🔹 Note

Limiti diversi possono essere applicati in base al tipo di utilizzo o accordi specifici.