Documentation de l'API

Une documentation minimale pour l'API publique de GeoPilot — chaque point de terminaison ci-dessous est monté sur /api/v1/public sur le domaine de votre déploiement GeoPilot, authentifié par une clé API plutôt qu'un cookie de session.

Journal des modifications

Ce qui a changé dans l'API publique, du plus récent au plus ancien. Une modification n'est marquée Breaking que lorsqu'une requête existante, correctement formée, se comporte désormais différemment ; le reste est un ajout ou une correction.

Ajouté27 Sept 2026

Les vérifications de conflits indiquent désormais les sources écartées

Les réponses de POST /restrictions/intersect contiennent un nouveau tableau excludedSources : chaque source non licenciée pour l'API dont la forme touche aussi des restrictions, avec un nombre, mais jamais les restrictions elles-mêmes. Auparavant, une vérification dans un tel pays renvoyait total: 0, ce qui se lisait comme une zone dégagée. Chaque conflit porte aussi sourceAttribution, la mention de la source, que les données CC BY vous obligent à afficher.

Ajouté23 Sept 2026

Description OpenAPI et catalogue d’API publiés

L’API publique est désormais décrite en OpenAPI 3.1 à /api/v1/public/openapi.json, générée à partir des mêmes schémas que ceux avec lesquels l’API valide les requêtes, et répertoriée dans un catalogue RFC 9727 à /.well-known/api-catalog. Un point de disponibilité, GET /api/v1/public/health, répond sans clé. Aucune requête existante ne change de comportement.

Corrigé13 Sept 2026

Conversions ED-318 corrigées face à deux flux réels

Le codec ED-318 avait été construit à partir du schéma publié, sans flux réel pour le vérifier. Il est désormais vérifié directement face aux exports réels de Transportstyrelsen (Suède) et de l'ANAC (Portugal), et plusieurs correspondances de champs étaient erronées : l'orthographe de la valeur d'autorisation, l'emplacement de l'altitude (sur la géométrie, pas sur properties), et la façon dont la géométrie d'une zone à plusieurs volumes est représentée. Toute conversion vers ou depuis ED-318 — ed269-ed318, kml-ed318, geojson-ed318, et leurs sens inverses — peut renvoyer, pour un document ED-318 réel, un résultat différent et corrigé par rapport à avant cette correction.

Obtenir une clé

L'accès API est un produit distinct de l'abonnement carte, facturé séparément et disponible en libre-service dès que votre compte y a droit.

Nouveau ici ? S'abonner à l'accès API

Vous voulez essayer avant d'acheter, ou avez-vous besoin d'une limite de débit personnalisée ? Demander un accès

Déjà abonné ? Créez une clé depuis votre profil — nommez-la, choisissez uniquement les portées dont vous avez besoin, et copiez la clé brute lorsqu'elle s'affiche, car elle ne s'affiche qu'une seule fois. Gérer les clés API

Authentification

Chaque requête transporte votre clé comme jeton bearer.

Authorization: Bearer <your-api-key>

Deux états d'échec sont distingués :

Clé manquante, malformée, inconnue, révoquée ou expirée — 401 Unauthorized.
Une clé valide dont l'accès API du propriétaire a expiré (abonnement annulé ou expiré) — 403 Forbidden.
Une clé valide qui ne possède pas la portée requise par un point de terminaison — 403 Forbidden, indiquant la portée manquante.

Portées

Chaque clé est créée avec une ou plusieurs portées. Une requête nécessite la portée exigée par son point de terminaison, indépendamment du fait que le compte dispose ou non d'un accès API.

RESTRICTIONS_READ: Lire les données de restriction d'espace aérien — liste, point, rayon et recherche par restriction unique.
CONFLICT_CHECK: Vérifier une zone ou un itinéraire tracé par rapport aux restrictions actives.
CONVERT_ED269: Convertir entre ED-269 et GeoJSON.
CONVERT_KML: Convertir entre KML et tout autre format pris en charge.
CONVERT_ED318: Convertir entre ED-318 et tout autre format pris en charge.

Limites de débit

Chaque quota ci-dessous est compté par clé, sur une fenêtre glissante d'une minute. Chaque réponse inclut X-RateLimit-Limit et X-RateLimit-Remaining ; une réponse 429 inclut également Retry-After.

Conversion: /convert/ed269-to-geojson, /convert/geojson-to-ed269, /convert/:from-:to; 60 requêtes par minute (par défaut).
Lectures de restrictions: /restrictions, /at, /near, /:id; 60 requêtes et 200 Mo par minute (par défaut).
Vérification de conflit: /restrictions/intersect; 60 requêtes par minute (par défaut).

Besoin d'une limite plus élevée pour une intégration particulière ? Demander un accès

Erreurs

Chaque échec — quel que soit le point de terminaison — a la même forme JSON (RFC 9457, « problem details »), afin que votre client puisse gérer un seul type d'erreur plutôt que de deviner pour chaque point de terminaison.

{
  "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 liste les échecs de validation au niveau des champs et n'apparaît que pour une réponse 400 ou 422.

400: Le corps de la requête, les paramètres de requête ou les paramètres de route ont échoué à la validation.
401: Clé manquante, malformée, inconnue, révoquée ou expirée.
403: Le titulaire de la clé n'a plus d'accès API actif, ou la clé n'a pas la portée requise par le point de terminaison.
404: La ressource demandée n'existe pas, ou n'est pas visible pour votre clé — voir la note sur les licences ci-dessus.
422: La géométrie soumise est invalide ou trop complexe pour être évaluée.
429: Limite de débit dépassée. Réessayez après le nombre de secondes indiqué dans Retry-After.

Pays couverts par l'API

L'API ne sert que les données des sources dont l'éditeur autorise la réutilisation commerciale et la redistribution ; elle couvre donc moins de pays que la carte. Ailleurs, les lectures de restrictions ne renvoient rien, et une vérification des conflits indique les sources écartées dans excludedSources au lieu de déclarer la zone dégagée.

Couverts:: Australie, Finlande, Luxembourg, Norvège, Suisse, États-Unis
Sur la carte uniquement (conditions de réutilisation non établies):: Lettonie, Portugal, Roumanie

Points de terminaison

Les lectures de restrictions ne renvoient que les données des sources dont la licence autorise l'usage commercial et la redistribution. Une source exclue pour cette raison se comporte comme si elle n'existait pas : GET /restrictions/:id renvoie 404 pour elle, exactement comme pour un id inconnu. La vérification des conflits est la seule exception : elle nomme ce qu'elle a écarté dans excludedSources, afin qu'un pays exclu ne soit jamais déclaré dégagé.

GET /api/v1/public/restrictions

Scope: RESTRICTIONS_READ

Lister les restrictions, filtrables par pays, boîte englobante, type, effet et plus.

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

Réponse

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

Toutes les restrictions des données de l'API superposées en un point.

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

Réponse

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

Restrictions dans un rayon autour d'un point, les plus proches en premier.

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

Réponse

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

Une restriction, par id.

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

Réponse

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

Vérifier un polygone ou un itinéraire par rapport aux restrictions actives et signaler ce qu'il rencontre.

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éponse

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

Convertir un document ED-269 publié en une collection d'éléments 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éponse

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

Convertir un élément ou une collection d'éléments GeoJSON en 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éponse

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

Points de terminaison — /convert/:from-:to

Au-delà des deux points de terminaison ED-269⇄GeoJSON ci-dessus, POST /convert/:from-:to convertit entre deux formats quelconques parmi ED-269, ED-318, KML et GeoJSON — douze paires dirigées au total, listées ci-dessous avec la ou les portées requises pour chacune. ed269-geojson et geojson-ed269 sous cette URL courte se comportent à l'identique des deux points de terminaison dédiés ci-dessus et coexistent avec eux ; les deux formes restent fonctionnelles.

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

Convertir un document ED-269 publié en 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éponse

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

Convertir un document KML en 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éponse

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