Vai al contenuto principale
GeoPilot

Documentazione dell'API

Una documentazione essenziale dell'API pubblica di GeoPilot: ogni endpoint qui sotto è montato su /api/v1/public nel dominio della tua installazione di GeoPilot ed è autenticato tramite una chiave API anziché un cookie di sessione.

Come differiscono ED-269 ed ED-318, campo per campo: leggi la guida. →

API delle zone vietate ai droni: primi passi →

Come convertire le geozone ED-269 ed ED-318 in GeoJSON o KML →

In formato leggibile dalle macchine: la descrizione OpenAPI 3.1 →

Registro delle modifiche

Cosa è cambiato nell'API pubblica, dal più recente. Una modifica è segnata come Incompatibile solo quando una richiesta esistente e formulata correttamente ora si comporta in modo diverso; tutto il resto è un'aggiunta o una correzione.

Aggiunto

Le verifiche dei conflitti ora indicano le fonti escluse

Le risposte di POST /restrictions/intersect contengono un nuovo array excludedSources: ogni fonte non licenziata per l'API le cui restrizioni la forma interseca, con un conteggio, ma mai le restrizioni stesse. Prima una verifica in un paese simile restituiva total: 0, che sembrava un'area libera. Ogni conflitto riporta anche sourceAttribution, la citazione della fonte, che i dati CC BY ti obbligano a mostrare.

Aggiunto

Pubblicati la descrizione OpenAPI e il catalogo API

L'API pubblica è ora descritta in OpenAPI 3.1 su /api/v1/public/openapi.json, generata dagli stessi schemi con cui l'API convalida le richieste, ed è elencata in un catalogo RFC 9727 su /.well-known/api-catalog. Un endpoint di verifica dell'operatività, GET /api/v1/public/health, risponde senza chiave. Nessuna richiesta esistente si comporta in modo diverso.

Corretto

Conversioni ED-318 corrette sulla base di due feed reali

Il codec ED-318 era stato costruito a partire dallo schema pubblicato, senza un feed reale con cui verificarlo. Ora è verificato direttamente su esportazioni reali, e diverse corrispondenze tra campi erano errate: la grafia del valore di autorizzazione, dove si trova l'altitudine (nella geometria, non nelle proprietà) e come è rappresentata la geometria di una zona con più volumi. Qualsiasi conversione da o verso ED-318 (ed269-ed318, kml-ed318, geojson-ed318 e le direzioni inverse) può restituire, per un documento ED-318 reale, un output diverso e corretto rispetto a prima di questa correzione.

Ottenere una chiave

L'accesso API è un prodotto separato dall'abbonamento alla mappa, fatturato a parte e in modalità self-service una volta che il tuo account ne dispone.

Sei nuovo? Abbonati all'accesso API

Vuoi provarlo prima di acquistarlo, o ti serve un limite di richieste personalizzato? Richiedi l'accesso

Hai già un abbonamento? Crea una chiave dal tuo profilo: dalle un nome, scegli solo gli ambiti che ti servono e copia la chiave completa quando viene mostrata, perché viene mostrata una sola volta. Gestisci le chiavi API

Autenticazione

Ogni richiesta porta la tua chiave come token bearer.

Authorization: Bearer <your-api-key>

Si distinguono due casi di errore:

  • Chiave mancante, malformata, sconosciuta, revocata o scaduta: 401 Unauthorized.
  • Una chiave valida il cui titolare non ha più accesso all'API (abbonamento annullato o scaduto): 403 Forbidden.
  • Una chiave valida che non ha l'ambito richiesto da un endpoint: 403 Forbidden, con l'indicazione dell'ambito mancante.

Ambiti

Ogni chiave viene creata con uno o più ambiti. Una richiesta necessita dell'ambito richiesto dal suo endpoint, indipendentemente dal fatto che l'account disponga o meno dell'accesso all'API.

RESTRICTIONS_READ
Lettura dei dati sulle restrizioni dello spazio aereo: elenco, punto, raggio e ricerca di una singola restrizione.
CONFLICT_CHECK
Verifica di un'area o di una rotta disegnata rispetto alle restrizioni attive.
CONVERT_ED269
Conversione tra ED-269 e GeoJSON.
CONVERT_KML
Conversione tra KML e qualsiasi altro formato supportato.
CONVERT_ED318
Conversione tra ED-318 e qualsiasi altro formato supportato.

Limiti di richieste

Ciascuna categoria qui sotto è conteggiata per chiave su una finestra mobile di un minuto. Ogni risposta include X-RateLimit-Limit e X-RateLimit-Remaining; una risposta 429 include anche Retry-After.

Conversione
/convert/ed269-to-geojson, /convert/geojson-to-ed269, /convert/:from-:to
60 richieste al minuto (predefinito).
Letture delle restrizioni
/restrictions, /at, /near, /:id
60 richieste e 200 MB al minuto (predefinito).
Verifica dei conflitti
/restrictions/intersect
60 richieste al minuto (predefinito).

Ti serve un limite più alto per un'integrazione specifica? Richiedi l'accesso

Errori

Ogni errore, da qualsiasi endpoint, ha la stessa forma JSON ("problem details" secondo RFC 9457), così il tuo client può gestire un unico percorso di errore invece di andare per tentativi endpoint per endpoint.

{
  "type": "https://geopilot.space/problems/forbidden",
  "title": "Insufficient permissions",
  "status": 403,
  "detail": "This API key does not have the CONFLICT_CHECK scope.",
  "instance": "/api/v1/public/restrictions/intersect",
  "requestId": "b3f2b8b0-8b7a-4c9b-9c9a-2f6a7a2b6b34"
}

errors elenca gli errori di convalida a livello di campo e compare solo con un 400 o un 422.

400
Il corpo, la query o i parametri della richiesta non hanno superato la convalida.
401
Chiave mancante, malformata, sconosciuta, revocata o scaduta.
403
Il titolare della chiave non ha più un accesso API attivo, oppure la chiave non ha l'ambito richiesto dall'endpoint.
404
La risorsa richiesta non esiste, oppure non è visibile alla tua chiave: vedi la nota sulle licenze qui sopra.
422
La geometria inviata non è valida o è troppo complessa da valutare.
429
Limite di richieste superato. Riprova dopo il numero di secondi indicato in Retry-After.

Paesi serviti dall'API

L'API serve solo dati provenienti da fonti i cui editori consentono il riutilizzo commerciale e la ridistribuzione, quindi copre meno paesi della mappa. Altrove le letture delle restrizioni non restituiscono nulla, e una verifica dei conflitti elenca in excludedSources le fonti escluse invece di dichiarare l'area libera.

Serviti:
Australia, Finlandia, Lussemburgo, Norvegia, Svizzera, Stati Uniti
Solo sulla mappa (condizioni di riutilizzo non stabilite):
Lettonia, Portogallo, Romania

Endpoint

Le letture delle restrizioni restituiscono solo dati provenienti da fonti la cui licenza consente l'uso commerciale e la ridistribuzione. Una fonte esclusa per questi motivi si comporta come se non esistesse: GET /restrictions/:id restituisce 404 esattamente come farebbe per un id sconosciuto. La verifica dei conflitti è l'unica eccezione: indica ciò che ha escluso in excludedSources, così un paese escluso non viene mai dichiarato libero.

GET /api/v1/public/restrictions

Scope: RESTRICTIONS_READ

Elenca le restrizioni, filtrabili per paese, riquadro di delimitazione, tipo, effetto e altro.

curl "https://geopilot.space/api/v1/public/restrictions?country=FI" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY"

Risposta

{
  "meta": {
    "freshness": {
      "state": "FRESH",
      "sources": [{ "sourceId": "fi-traficom-zones", "state": "FRESH", "lastSyncedAt": "2026-09-01T09:00:00.000Z" }],
      "generatedAt": "2026-09-01T12:00:00.000Z"
    },
    "pagination": { "limit": 1000, "nextCursor": null, "returned": 214, "truncated": false },
    "detail": "FULL",
    "attributions": ["Source: Finnish Transport and Communications Agency Traficom, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Modified by GeoPilot: geometry simplified, zones classified."],
    "sources": [
      {
        "id": "fi-traficom-zones",
        "providerKey": "fi-traficom-zones",
        "name": "Traficom UAS geographical zones",
        "attribution": "Source: Finnish Transport and Communications Agency Traficom, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Modified by GeoPilot: geometry simplified, zones classified.",
        "sourceTimestamp": "2026-09-01T06:00:00.000Z",
        "lastSyncedAt": "2026-09-01T09:00:00.000Z"
      }
    ],
    "authorities": [{ "id": "traficom", "name": "Traficom", "phone": null, "email": null, "website": null }],
    "evaluatedAt": "2026-09-01T12:00:00.000Z",
    "disclaimer": "GeoPilot is an independent planning tool and is not affiliated with or endorsed by any aviation authority. It shows data published by national authorities, which may be incomplete, out of date or simplified in processing, and it does not authorize any flight. Always check the authority's own publication and current NOTAMs before flying."
  },
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "id": "3f1b2c4d-0000-4000-8000-000000000000",
        "geometry": { "type": "Polygon", "coordinates": [[[24.90,60.29],[25.00,60.29],[25.00,60.35],[24.90,60.35],[24.90,60.29]]] },
        "properties": {
          "id": "3f1b2c4d-0000-4000-8000-000000000000",
          "externalId": "EF-UAS-EXAMPLE",
          "countryIso2": "FI",
          "name": "Example aerodrome UAS zone",
          "description": null,
          "type": "RESTRICTED_AREA",
          "effect": "AUTHORIZATION_REQUIRED",
          "effectBasis": "PROVIDER_RULE",
          "status": "ACTIVE",
          "lowerLimit": { "meters": 0, "datum": "GND", "raw": "GND", "parsed": true },
          "upperLimit": { "meters": 1500, "datum": "AMSL", "raw": "1500 AMSL", "parsed": true },
          "activationStart": null,
          "activationEnd": null,
          "schedule": null,
          "activeNow": true,
          "sourceId": "fi-traficom-zones",
          "authorityId": "traficom",
          "firstSeenAt": "2025-01-15T00:00:00.000Z",
          "lastSeenAt": "2026-09-01T09:00:00.000Z"
        }
      }
    ]
  }
}

GET /api/v1/public/restrictions/at

Scope: RESTRICTIONS_READ

Tutte le restrizioni nei dati dell'API sovrapposte in un punto.

curl "https://geopilot.space/api/v1/public/restrictions/at?lat=60.32&lon=24.95" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY"

Risposta

{
  "meta": { "…": "same shape as GET /restrictions, above" },
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "id": "3f1b2c4d-0000-4000-8000-000000000000",
        "geometry": { "type": "Polygon", "coordinates": [[[24.90,60.29],[25.00,60.29],[25.00,60.35],[24.90,60.35],[24.90,60.29]]] },
        "properties": {
          "id": "3f1b2c4d-0000-4000-8000-000000000000",
          "externalId": "EF-UAS-EXAMPLE",
          "name": "Example aerodrome UAS zone",
          "type": "RESTRICTED_AREA",
          "effect": "AUTHORIZATION_REQUIRED",
          "effectBasis": "PROVIDER_RULE",
          "status": "ACTIVE",
          "activeNow": true,
          "sourceId": "fi-traficom-zones",
          "authorityId": "traficom"
        }
      }
    ]
  }
}

GET /api/v1/public/restrictions/near

Scope: RESTRICTIONS_READ

Restrizioni entro un raggio da un punto, dalla più vicina.

curl "https://geopilot.space/api/v1/public/restrictions/near?lat=60.32&lon=24.95&radiusMeters=5000" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY"

Risposta

{
  "meta": { "…": "same shape as GET /restrictions, above" },
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "id": "3f1b2c4d-0000-4000-8000-000000000000",
        "geometry": { "type": "Polygon", "coordinates": [[[24.90,60.29],[25.00,60.29],[25.00,60.35],[24.90,60.35],[24.90,60.29]]] },
        "properties": {
          "id": "3f1b2c4d-0000-4000-8000-000000000000",
          "externalId": "EF-UAS-EXAMPLE",
          "name": "Example aerodrome UAS zone",
          "type": "RESTRICTED_AREA",
          "effect": "AUTHORIZATION_REQUIRED",
          "effectBasis": "PROVIDER_RULE",
          "status": "ACTIVE",
          "activeNow": true,
          "sourceId": "fi-traficom-zones",
          "authorityId": "traficom",
          "distanceMeters": 842.6
        }
      }
    ]
  }
}

GET /api/v1/public/restrictions/:id

Scope: RESTRICTIONS_READ

Una restrizione per id.

curl "https://geopilot.space/api/v1/public/restrictions/3f1b2c4d-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY"

Risposta

{
  "type": "Feature",
  "id": "3f1b2c4d-0000-4000-8000-000000000000",
  "geometry": { "type": "Polygon", "coordinates": [[[24.90,60.29],[25.00,60.29],[25.00,60.35],[24.90,60.35],[24.90,60.29]]] },
  "properties": {
    "id": "3f1b2c4d-0000-4000-8000-000000000000",
    "externalId": "EF-UAS-EXAMPLE",
    "countryIso2": "FI",
    "name": "Example aerodrome UAS zone",
    "description": null,
    "type": "RESTRICTED_AREA",
    "effect": "AUTHORIZATION_REQUIRED",
    "effectBasis": "PROVIDER_RULE",
    "status": "ACTIVE",
    "lowerLimit": { "meters": 0, "datum": "GND", "raw": "GND", "parsed": true },
    "upperLimit": { "meters": 1500, "datum": "AMSL", "raw": "1500 AMSL", "parsed": true },
    "activationStart": null,
    "activationEnd": null,
    "schedule": null,
    "activeNow": true,
    "authority": { "id": "traficom", "name": "Traficom", "phone": null, "email": null, "website": null },
    "source": {
      "id": "fi-traficom-zones",
      "providerKey": "fi-traficom-zones",
      "name": "Traficom UAS geographical zones",
      "attribution": "Source: Finnish Transport and Communications Agency Traficom, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Modified by GeoPilot: geometry simplified, zones classified.",
      "sourceTimestamp": "2026-09-01T06:00:00.000Z",
      "lastSyncedAt": "2026-09-01T09:00:00.000Z"
    },
    "raw": { "…": "the provider's original record, preserved verbatim" },
    "firstSeenAt": "2025-01-15T00:00:00.000Z",
    "lastSeenAt": "2026-09-01T09:00:00.000Z"
  }
}

POST /api/v1/public/restrictions/intersect

Scope: CONFLICT_CHECK

Verifica un poligono o una rotta rispetto alle restrizioni attive e riporta ciò che interseca.

curl -X POST "https://geopilot.space/api/v1/public/restrictions/intersect" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[24.90,60.29],[25.00,60.29],[25.00,60.35],[24.90,60.35],[24.90,60.29]]]
    }
  }'

Risposta

{
  "conflicts": [
    {
      "restrictionId": "3f1b2c4d-0000-4000-8000-000000000000",
      "externalId": "EF-UAS-EXAMPLE",
      "name": "Example aerodrome UAS zone",
      "type": "RESTRICTED_AREA",
      "effect": "AUTHORIZATION_REQUIRED",
      "effectBasis": "PROVIDER_RULE",
      "authorityName": "Traficom",
      "intersectionAreaM2": 482310.5,
      "intersectionRatio": 0.61,
      "activeAtQueryTime": true,
      "sourceName": "Traficom UAS geographical zones",
      "sourceAttribution": "Source: Finnish Transport and Communications Agency Traficom, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Modified by GeoPilot: geometry simplified, zones classified."
    }
  ],
  "summary": { "total": 1, "prohibited": 0, "authorizationRequired": 1, "coordinationRequired": 0, "informationOnly": 0, "unknown": 0 },
  "evaluatedAt": "2026-09-01T12:00:00.000Z",
  "disclaimer": "GeoPilot is an independent planning tool and is not affiliated with or endorsed by any aviation authority. It shows data published by national authorities, which may be incomplete, out of date or simplified in processing, and it does not authorize any flight. Always check the authority's own publication and current NOTAMs before flying.",
  "excludedSources": []
}

POST /api/v1/public/convert/ed269-to-geojson

Scope: CONVERT_ED269

Converte un documento ED-269 pubblicato in una FeatureCollection GeoJSON.

curl -X POST "https://geopilot.space/api/v1/public/convert/ed269-to-geojson" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document": { "UASZoneVersion": { "...": "the published ED-269 document" } } }'

Risposta

{
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "Polygon", "coordinates": [[[26.05,44.40],[26.15,44.40],[26.15,44.47],[26.05,44.47],[26.05,44.40]]] },
        "properties": {
          "externalId": "ROU-001",
          "name": "Example zone",
          "description": null,
          "type": "OTHER",
          "effect": "PROHIBITED",
          "effectBasis": "PROVIDER_RULE",
          "lowerLimit": { "meters": 0, "datum": "AGL", "display": "0 m AGL" },
          "upperLimit": { "meters": 120, "datum": "AGL", "display": "120 m AGL" },
          "activationStart": null,
          "activationEnd": null,
          "schedule": null,
          "authorityHint": null
        }
      }
    ]
  },
  "errors": [],
  "totalFeatures": 1
}

POST /api/v1/public/convert/geojson-to-ed269

Scope: CONVERT_ED269

Converte una Feature o una FeatureCollection GeoJSON in un documento ED-269.

curl -X POST "https://geopilot.space/api/v1/public/convert/geojson-to-ed269" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Feature",
    "geometry": { "type": "Polygon", "coordinates": [[[26.05,44.40],[26.15,44.40],[26.15,44.47],[26.05,44.47],[26.05,44.40]]] },
    "properties": { "name": "Example zone", "effect": "PROHIBITED" }
  }'

Risposta

{
  "document": {
    "title": "GeoPilot ED-269 export",
    "description": "Generated by GeoPilot's GeoJSON → ED-269 conversion endpoint.",
    "features": [
      {
        "name": "Example zone",
        "type": "CUSTOMIZED",
        "restriction": "PROHIBITED",
        "applicability": [],
        "zoneAuthority": [],
        "geometry": [
          {
            "uomDimensions": "M",
            "horizontalProjection": {
              "type": "Polygon",
              "coordinates": [[[26.05,44.40],[26.15,44.40],[26.15,44.47],[26.05,44.47],[26.05,44.40]]]
            }
          }
        ]
      }
    ]
  },
  "warnings": []
}

Endpoint — /convert/:from-:to

Oltre ai due endpoint ED-269⇄GeoJSON qui sopra, POST /convert/:from-:to converte tra due qualsiasi tra ED-269, ED-318, KML e GeoJSON: dodici coppie orientate in totale, elencate qui sotto con gli ambiti richiesti da ciascuna. ed269-geojson e geojson-ed269 con questo URL breve si comportano in modo identico ai due endpoint dedicati qui sopra e coesistono con essi; entrambe le forme continuano a funzionare.

fromtoscope(s) required
ed269ed318CONVERT_ED269 + CONVERT_ED318
ed269kmlCONVERT_ED269 + CONVERT_KML
ed269geojsonCONVERT_ED269
ed318ed269CONVERT_ED318 + CONVERT_ED269
ed318kmlCONVERT_ED318 + CONVERT_KML
ed318geojsonCONVERT_ED318
kmled269CONVERT_KML + CONVERT_ED269
kmled318CONVERT_KML + CONVERT_ED318
kmlgeojsonCONVERT_KML
geojsoned269CONVERT_ED269
geojsoned318CONVERT_ED318
geojsonkmlCONVERT_KML

POST /api/v1/public/convert/ed269-kml

Scope: CONVERT_ED269 + CONVERT_KML

Converte un documento ED-269 pubblicato in un documento KML.

curl -X POST "https://geopilot.space/api/v1/public/convert/ed269-kml" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document": { "title": "t", "features": [ { "identifier": "ROU-001", "name": "Example zone", "restriction": "PROHIBITED", "geometry": [ { "uomDimensions": "M", "horizontalProjection": { "type": "Polygon", "coordinates": [[[26.05,44.40],[26.15,44.40],[26.15,44.47],[26.05,44.47],[26.05,44.40]]] } } ] } ] } }'

Risposta

{
  "document": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<kml xmlns=\"http://www.opengis.net/kml/2.2\">\n  <Document>\n    <Placemark>\n      <name>Example zone</name>\n      <ExtendedData>\n        <Data name=\"effect\"><value>PROHIBITED</value></Data>\n      </ExtendedData>\n      <Polygon>\n        <altitudeMode>clampToGround</altitudeMode>\n        <outerBoundaryIs><LinearRing><coordinates>26.05,44.40,0 26.15,44.40,0 26.15,44.47,0 26.05,44.47,0 26.05,44.40,0</coordinates></LinearRing></outerBoundaryIs>\n      </Polygon>\n    </Placemark>\n  </Document>\n</kml>",
  "errors": [],
  "totalFeatures": 1,
  "warnings": []
}

POST /api/v1/public/convert/kml-ed318

Scope: CONVERT_KML + CONVERT_ED318

Converte un documento KML in un documento ED-318.

curl -X POST "https://geopilot.space/api/v1/public/convert/kml-ed318" \
  -H "Authorization: Bearer $GEOPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document": "<kml><Document><Placemark><name>Example zone</name><ExtendedData><Data name=\"effect\"><value>PROHIBITED</value></Data></ExtendedData><Polygon><outerBoundaryIs><LinearRing><coordinates>26.05,44.40,0 26.15,44.40,0 26.15,44.47,0 26.05,44.47,0 26.05,44.40,0</coordinates></LinearRing></outerBoundaryIs></Polygon></Placemark></Document></kml>" }'

Risposta

{
  "document": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "Polygon", "coordinates": [[[26.05,44.40],[26.15,44.40],[26.15,44.47],[26.05,44.47],[26.05,44.40]]] },
        "properties": {
          "name": "Example zone",
          "type": "CUSTOMIZED",
          "restriction": "PROHIBITED",
          "applicability": [],
          "zoneAuthority": [],
          "uomDimensions": "M"
        }
      }
    ]
  },
  "errors": [],
  "totalFeatures": 1,
  "warnings": []
}
GeoPilot

Uno strumento indipendente per pianificare i voli con i droni, basato sulle restrizioni dello spazio aereo pubblicate dalle autorità nazionali, per i paesi europei coperti e per gli Stati Uniti.

Dati

  • I dati sullo spazio aereo sono pubblicati dalle autorità nazionali di ciascun paese coperto. GeoPilot non è affiliato né approvato da nessuna di esse.
  • Vedi fonti e aggiornamento

GeoPilot è uno strumento di pianificazione indipendente e non è affiliato né approvato da alcuna autorità aeronautica. Mostra dati pubblicati dalle autorità nazionali, che possono essere incompleti, non aggiornati o semplificati nell'elaborazione, e non autorizza alcun volo. Prima di volare, verifica sempre la pubblicazione dell'autorità stessa e i NOTAM in vigore.