Referência da API

Uma referência mínima da API pública do GeoPilot — todos os endpoints abaixo estão montados em /api/v1/public no domínio da sua instalação do GeoPilot e são autenticados por uma chave de API, não por um cookie de sessão.

Registo de alterações

O que mudou na API pública, das alterações mais recentes para as mais antigas. Uma alteração só é marcada como Incompatível quando um pedido existente e corretamente formado passa a comportar-se de outra forma; tudo o resto é um acréscimo ou uma correção.

Adicionado27 Sept 2026

As verificações de conflitos indicam agora as fontes deixadas de fora

As respostas de POST /restrictions/intersect incluem um novo array excludedSources: cada fonte não licenciada para a API cujas restrições a forma também interseta, com uma contagem, mas nunca as próprias restrições. Antes, uma verificação num país assim devolvia total: 0, o que parecia uma área livre. Cada conflito inclui também sourceAttribution, a menção da fonte, que os dados CC BY exigem que mostre.

Adicionado23 Sept 2026

Descrição OpenAPI e catálogo da API publicados

A API pública está agora descrita em OpenAPI 3.1 em /api/v1/public/openapi.json, gerada a partir dos mesmos esquemas com que a API valida os pedidos, e listada num catálogo RFC 9727 em /.well-known/api-catalog. Um endpoint de disponibilidade, GET /api/v1/public/health, responde sem chave. Nenhum pedido existente passa a comportar-se de outra forma.

Corrigido13 Sept 2026

Conversões ED-318 corrigidas com base em dois feeds reais

O codec ED-318 tinha sido construído a partir do esquema publicado, sem nenhum feed real com que o verificar. Agora é verificado diretamente face a exportações reais, e vários mapeamentos de campos estavam errados: a grafia do valor de autorização, onde a altitude é indicada (na geometria, não nas propriedades) e a forma como é representada a geometria de uma zona com vários volumes. Qualquer conversão de ou para ED-318 — ed269-ed318, kml-ed318, geojson-ed318 e os sentidos inversos — pode devolver, para um documento ED-318 real, um resultado diferente e corrigido em relação ao anterior a esta correção.

Obter uma chave

O acesso à API é um produto separado da subscrição do mapa, faturado à parte e em regime de self-service a partir do momento em que a sua conta o tiver.

É a primeira vez que cá vem? Subscrever o acesso à API

Quer experimentar antes de comprar ou precisa de um limite de pedidos personalizado? Candidatar-se ao acesso

Já é subscritor? Crie uma chave a partir do seu perfil — dê-lhe um nome, escolha apenas os âmbitos de que precisa e copie a chave completa quando for apresentada, pois só é mostrada uma vez. Gerir chaves de API

Autenticação

Cada pedido inclui a sua chave como token bearer.

Authorization: Bearer <your-api-key>

São distinguidos dois estados de falha:

Chave em falta, mal formada, desconhecida, revogada ou expirada — 401 Unauthorized.
Uma chave válida cujo titular deixou de ter acesso à API (subscrição cancelada ou expirada) — 403 Forbidden.
Uma chave válida que não tem o âmbito exigido por um endpoint — 403 Forbidden, com a indicação do âmbito em falta.

Âmbitos

Cada chave é criada com um ou mais âmbitos. Um pedido precisa do âmbito exigido pelo respetivo endpoint, independentemente de a conta ter ou não acesso à API.

RESTRICTIONS_READ: Ler dados de restrições do espaço aéreo — consultas de lista, ponto, raio e restrição individual.
CONFLICT_CHECK: Verificar uma área ou rota desenhada face às restrições ativas.
CONVERT_ED269: Converter entre ED-269 e GeoJSON.
CONVERT_KML: Converter entre KML e qualquer outro formato suportado.
CONVERT_ED318: Converter entre ED-318 e qualquer outro formato suportado.

Limites de pedidos

Cada categoria abaixo é contabilizada por chave numa janela móvel de um minuto. Todas as respostas incluem X-RateLimit-Limit e X-RateLimit-Remaining; uma resposta 429 inclui também Retry-After.

Conversão: /convert/ed269-to-geojson, /convert/geojson-to-ed269, /convert/:from-:to; 60 pedidos por minuto (predefinição).
Leituras de restrições: /restrictions, /at, /near, /:id; 60 pedidos e 200 MB por minuto (predefinição).
Verificação de conflitos: /restrictions/intersect; 60 pedidos por minuto (predefinição).

Precisa de um limite mais alto para uma integração específica? Candidatar-se ao acesso

Erros

Todas as falhas — de todos os endpoints — têm a mesma estrutura JSON ("problem details" do RFC 9457), para que o seu cliente possa tratar um único caminho de erro em vez de adivinhar endpoint a 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 lista as falhas de validação ao nível dos campos e só aparece numa resposta 400 ou 422.

400: O corpo, a query ou os parâmetros do pedido não passaram na validação.
401: Chave em falta, mal formada, desconhecida, revogada ou expirada.
403: O titular da chave já não tem acesso ativo à API, ou a chave não tem o âmbito exigido pelo endpoint.
404: O recurso pedido não existe ou não está visível para a sua chave — consulte a nota sobre licenças acima.
422: A geometria enviada é inválida ou demasiado complexa para ser avaliada.
429: Limite de pedidos excedido. Tente novamente após o número de segundos indicado em Retry-After.

Países servidos pela API

A API só serve dados de fontes cujas entidades publicadoras permitem a reutilização comercial e a redistribuição, pelo que abrange menos países do que o mapa. Noutros locais, as leituras de restrições não devolvem nada, e uma verificação de conflitos indica em excludedSources as fontes que deixou de fora, em vez de dar a área como livre.

Servidos:: Austrália, Finlândia, Luxemburgo, Noruega, Suíça, Estados Unidos
Apenas no mapa (condições de reutilização não estabelecidas):: Letónia, Portugal, Roménia

Endpoints

As leituras de restrições só devolvem dados de fontes cuja licença permita a utilização comercial e a redistribuição. Uma fonte excluída por esses motivos comporta-se como se não existisse: GET /restrictions/:id devolve 404 para ela, exatamente como para um id desconhecido. A verificação de conflitos é a única exceção: indica o que deixou de fora em excludedSources, para que um país excluído nunca seja dado como livre.

GET /api/v1/public/restrictions

Scope: RESTRICTIONS_READ

Listar restrições, com filtros por país, caixa delimitadora, tipo, efeito e mais.

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

Resposta

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

Todas as restrições nos dados da API sobrepostas num ponto.

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

Resposta

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

Restrições num raio em torno de um ponto, das mais próximas para as mais distantes.

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

Resposta

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

Uma restrição por id.

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

Resposta

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

Verificar um polígono ou rota face às restrições ativas e indicar o que interseta.

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

Resposta

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

Converter um documento ED-269 publicado numa 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" } } }'

Resposta

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

Converter uma Feature ou FeatureCollection GeoJSON num 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" }
  }'

Resposta

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

Endpoints — /convert/:from-:to

Para além dos dois endpoints ED-269⇄GeoJSON acima, POST /convert/:from-:to converte entre quaisquer dois formatos de entre ED-269, ED-318, KML e GeoJSON — doze pares orientados no total, listados abaixo com o(s) âmbito(s) que cada um exige. ed269-geojson e geojson-ed269 neste URL curto comportam-se de forma idêntica aos dois endpoints dedicados acima e coexistem com eles; ambas as formas continuam a funcionar.

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

Converter um documento ED-269 publicado num 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]]] } } ] } ] } }'

Resposta

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

Converter um documento KML num 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>" }'

Resposta

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