Documentație API

O documentație minimală pentru API-ul public GeoPilot — fiecare punct final de mai jos este montat la /api/v1/public pe domeniul instanței tale GeoPilot, autentificat printr-o cheie API, nu printr-un cookie de sesiune.

Istoric modificări

Ce s-a schimbat în API-ul public, de la cel mai recent la cel mai vechi. O modificare este marcată Breaking doar atunci când o cerere existentă, corect formată, se comportă altfel decât înainte; restul sunt adăugări sau corecturi.

Adăugat27 Sept 2026

Verificările conflictelor spun acum ce surse au omis

Răspunsurile POST /restrictions/intersect conțin un nou tablou excludedSources: fiecare sursă nelicențiată pentru API ale cărei restricții sunt atinse de formă, cu un număr, dar niciodată restricțiile în sine. Înainte, o verificare într-o astfel de țară returna total: 0, ceea ce părea o zonă liberă. Fiecare conflict conține și sourceAttribution, mențiunea sursei, pe care datele CC BY îți cer să o afișezi.

Adăugat23 Sept 2026

Descrierea OpenAPI și catalogul API publicate

API-ul public este acum descris în format OpenAPI 3.1 la /api/v1/public/openapi.json, generat din aceleași scheme cu care API-ul validează cererile, și listat într-un catalog RFC 9727 la /.well-known/api-catalog. Un endpoint de disponibilitate, GET /api/v1/public/health, răspunde fără cheie. Nicio cerere existentă nu se comportă diferit.

Corectat13 Sept 2026

Conversiile ED-318 au fost corectate față de două fluxuri reale

Codecul ED-318 fusese construit după schema publicată, fără un flux real cu care să fie verificat. Acum este verificat direct față de exporturile reale ale Transportstyrelsen (Suedia) și ANAC (Portugalia), iar mai multe corespondențe de câmpuri erau greșite: modul de scriere a valorii de autorizare, locul unde este transmisă altitudinea (pe geometrie, nu pe properties) și modul în care este reprezentată geometria unei zone cu mai multe volume. Orice conversie către sau de la ED-318 — ed269-ed318, kml-ed318, geojson-ed318 și sensurile inverse — poate returna, pentru un document ED-318 real, un rezultat diferit și corectat față de înainte de această remediere.

Obținerea unei chei

Accesul API este un produs separat de abonamentul pentru hartă, facturat independent și disponibil prin auto-servire imediat ce contul tău îl deține.

Ești nou aici? Abonează-te la acces API

Vrei să încerci înainte de a cumpăra sau ai nevoie de o limită de rată personalizată? Solicită acces

Ești deja abonat? Creează o cheie din profilul tău — denumește-o, alege doar permisiunile de care ai nevoie și copiază cheia brută atunci când este afișată, deoarece este afișată o singură dată. Gestionează cheile API

Autentificare

Fiecare cerere transmite cheia ta ca token bearer.

Authorization: Bearer <your-api-key>

Sunt distinse două stări de eșec:

Cheie lipsă, malformată, necunoscută, revocată sau expirată — 401 Unauthorized.
O cheie validă al cărei acces API al proprietarului a expirat (abonament anulat sau expirat) — 403 Forbidden.
O cheie validă care nu deține permisiunea cerută de un punct final — 403 Forbidden, cu numele permisiunii lipsă.

Permisiuni

Fiecare cheie este creată cu una sau mai multe permisiuni. O cerere are nevoie de permisiunea cerută de punctul final respectiv, indiferent dacă acel cont are acces API în general.

RESTRICTIONS_READ: Citește date despre restricțiile de spațiu aerian — listă, punct, rază și căutare după o singură restricție.
CONFLICT_CHECK: Verifică o zonă sau o rută desenată față de restricțiile active.
CONVERT_ED269: Convertește între ED-269 și GeoJSON.
CONVERT_KML: Convertește între KML și oricare alt format acceptat.
CONVERT_ED318: Convertește între ED-318 și oricare alt format acceptat.

Limite de rată

Fiecare grup de mai jos este contorizat per cheie, pe o fereastră glisantă de un minut. Fiecare răspuns include X-RateLimit-Limit și X-RateLimit-Remaining; un răspuns 429 include și Retry-After.

Conversie: /convert/ed269-to-geojson, /convert/geojson-to-ed269, /convert/:from-:to; 60 de cereri pe minut (implicit).
Citiri de restricții: /restrictions, /at, /near, /:id; 60 de cereri și 200 MB pe minut (implicit).
Verificare de conflict: /restrictions/intersect; 60 de cereri pe minut (implicit).

Ai nevoie de o limită mai mare pentru o integrare anume? Solicită acces

Erori

Fiecare eșec — de la orice punct final — are aceeași formă JSON (RFC 9457, „problem details”), astfel încât clientul tău poate trata un singur tip de eroare în loc să ghicească pentru fiecare punct final.

{
  "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 listează erorile de validare la nivel de câmp și apare doar pentru un răspuns 400 sau 422.

400: Corpul cererii, parametrii de interogare sau parametrii de rută nu au trecut validarea.
401: Cheie lipsă, malformată, necunoscută, revocată sau expirată.
403: Proprietarul cheii nu mai are acces API activ, sau cheia nu are permisiunea cerută de punctul final.
404: Resursa cerută nu există sau nu este vizibilă pentru cheia ta — vezi nota despre licențiere de mai sus.
422: Geometria trimisă este invalidă sau prea complexă pentru a fi evaluată.
429: Limita de rată a fost depășită. Reîncearcă după numărul de secunde indicat în Retry-After.

Țările deservite de API

API-ul servește doar date din surse ai căror publicatori permit reutilizarea comercială și redistribuirea, deci acoperă mai puține țări decât harta. În rest, citirile de restricții nu returnează nimic, iar o verificare a conflictelor listează sursele omise în excludedSources, în loc să raporteze zona ca liberă.

Deservite:: Australia, Finlanda, Luxemburg, Norvegia, Elveția, Statele Unite ale Americii
Doar pe hartă (condiții de reutilizare nestabilite):: Letonia, Portugalia, România

Puncte finale

Citirile de restricții returnează doar date din surse a căror licență permite utilizarea comercială și redistribuirea. O sursă exclusă din acest motiv se comportă ca și cum nu ar exista: GET /restrictions/:id returnează 404 pentru ea exact ca pentru un id necunoscut. Verificarea conflictelor este singura excepție: numește ce a omis în excludedSources, astfel încât o țară exclusă nu este niciodată raportată ca liberă.

GET /api/v1/public/restrictions

Scope: RESTRICTIONS_READ

Listează restricțiile, filtrabile după țară, casetă de delimitare, tip, efect și altele.

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

Răspuns

{
  "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

Toate restricțiile din datele API suprapuse într-un punct.

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

Răspuns

{
  "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

Restricții într-o rază față de un punct, în ordinea apropierii.

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

Răspuns

{
  "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

O singură restricție, după id.

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

Răspuns

{
  "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

Verifică un poligon sau o rută față de restricțiile active și raportează ce întâlnește.

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]]]
    }
  }'

Răspuns

{
  "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ște un document ED-269 publicat într-o colecție de elemente 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" } } }'

Răspuns

{
  "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ște un element sau o colecție de elemente GeoJSON într-un document 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" }
  }'

Răspuns

{
  "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": []
}

Puncte finale — /convert/:from-:to

Pe lângă cele două puncte finale ED-269⇄GeoJSON de mai sus, POST /convert/:from-:to convertește între oricare două dintre ED-269, ED-318, KML și GeoJSON — douăsprezece perechi direcționate în total, listate mai jos împreună cu permisiunea (permisiunile) cerute de fiecare. ed269-geojson și geojson-ed269 sub această adresă scurtă se comportă identic cu cele două puncte finale dedicate de mai sus și coexistă cu ele; ambele forme rămân funcționale.

from	to	scope(s) required
ed269	ed318	CONVERT_ED269 + CONVERT_ED318
ed269	kml	CONVERT_ED269 + CONVERT_KML
ed269	geojson	CONVERT_ED269
ed318	ed269	CONVERT_ED318 + CONVERT_ED269
ed318	kml	CONVERT_ED318 + CONVERT_KML
ed318	geojson	CONVERT_ED318
kml	ed269	CONVERT_KML + CONVERT_ED269
kml	ed318	CONVERT_KML + CONVERT_ED318
kml	geojson	CONVERT_KML
geojson	ed269	CONVERT_ED269
geojson	ed318	CONVERT_ED318
geojson	kml	CONVERT_KML

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

Scope: CONVERT_ED269 + CONVERT_KML

Convertește un document ED-269 publicat într-un document 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]]] } } ] } ] } }'

Răspuns

{
  "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ște un document KML într-un document 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>" }'

Răspuns

{
  "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": []
}