O que é GeoJSON? Formato, Tipos de Geometria e Armadilhas em Produção

GeoJSON é o formato baseado em JSON que todo mapa web moderno consegue ler. Se você já desenhou um polígono em um mapa Leaflet, estilizou uma camada vetorial em MapLibre ou armazenou uma área de serviço no PostGIS, você já trabalhou com GeoJSON, mesmo que a extensão do arquivo dissesse outra coisa.

Este guia explica o que GeoJSON realmente é, o que seus tipos de geometria significam, onde aparece em sistemas reais, e as armadilhas que mordem os times quando arquivos GeoJSON saem do laptop do dev e batem em produção.

O que GeoJSON Realmente É

GeoJSON é um formato aberto para codificar estruturas de dados geográficas, padronizado pela IETF como RFC 7946 em 2016. É um subset estrito de JSON: todo documento GeoJSON é JSON válido, mas a spec adiciona regras sobre quais chaves são permitidas, como a geometria é estruturada e como as coordenadas são ordenadas.

O formato é intencionalmente pequeno. Existem apenas nove tipos de objeto top-level em toda a spec, e um dev competente consegue manter todos eles na cabeça. Essa pequenez é por que GeoJSON virou a língua franca do web mapping: é fácil de ler, fácil de escrever e fácil de validar.

Coordenadas são sempre escritas como [longitude, latitude] (com altitude opcional como terceiro valor), e o sistema de referência de coordenadas é fixado em WGS84, o mesmo datum que o GPS do seu celular usa. Não há negociação, nem metadados de projeção, nem debate sobre ordem de eixo. Um datum, uma ordem, em todo lugar.

Tipos de Geometria

GeoJSON define sete tipos de geometria. Os três primeiros são as primitivas:

• Point: uma única coordenada, usada para pins, endereços e sensores individuais
• LineString: uma lista ordenada de duas ou mais coordenadas, usada para rotas, ruas e rios
• Polygon: um anel fechado de coordenadas (primeiro e último ponto idênticos), usado para prédios, lotes e fronteiras administrativas

Os próximos três são simplesmente coleções dessas primitivas:

• MultiPoint: muitos pontos em uma única geometria, útil para representar uma rede de lojas como uma única feature
• MultiLineString: muitas line strings, usado para rotas fragmentadas ou sistemas de rios
• MultiPolygon: muitos polígonos, a escolha certa para qualquer país com ilhas (então, quase todos)

O sétimo, GeometryCollection, pode segurar uma mistura de qualquer um dos acima. A spec desencoraja porque a maioria dos consumidores lida com isso mal, e você quase nunca precisa. Se você está alcançando GeometryCollection, geralmente é sinal de que o modelo quer ser uma FeatureCollection.

Feature e FeatureCollection

Uma geometria sozinha raramente é útil. Você precisa saber o que ela representa. É para isso que Feature existe: uma Feature envolve uma geometria com um objeto properties que segura metadados arbitrários.

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [4.8952, 52.3702]
  },
  "properties": {
    "name": "Amsterdam Centraal",
    "type": "station",
    "platforms": 15
  }
}

Uma FeatureCollection é uma lista de Features. Quase todo arquivo GeoJSON real que você vai encontrar na natureza é uma FeatureCollection, porque datasets reais têm muitas coisas dentro.

A escolha de design crucial é que properties é aberto. A spec não diz nada sobre quais chaves pode conter ou quais tipos esses valores devem ter. Isso é uma feature, não um bug: significa que GeoJSON funciona para mobiliário urbano, fronteiras eleitorais, zonas de entrega e tracks de navios AIS sem ter que estender o formato. Também significa que consumidores precisam ter cuidado: se você depende de properties.population existir, valide você mesmo, porque RFC 7946 não vai validar.

Onde GeoJSON Aparece

Uma vez que você começa a olhar, GeoJSON está em todo lugar na stack geoespacial:

• Bibliotecas de mapas: MapLibre GL, Mapbox GL, Leaflet e OpenLayers todos consomem GeoJSON nativamente como fonte de dados para camadas
• Pipelines de vector tile: ferramentas como Tippecanoe pegam GeoJSON na entrada e produzem MVT (Mapbox Vector Tile) na saída
• Specs de estilo de mapa: a Mapbox Style Specification, usada pelo MapLibre, referencia GeoJSON como tipo de fonte de primeira classe
• Bancos espaciais: PostGIS, BigQuery GIS e Snowflake todos importam e exportam GeoJSON via funções dedicadas
• Saídas de API: a maioria das geocoding, isochrone e routing APIs modernas retorna Features GeoJSON para resultados, então a resposta pode ser jogada direto em um mapa
• Polylines de rota: respostas de navegação comumente incluem uma geometria LineString para a rota, pronta para renderizar
• Compartilhamento de dados: portais de open data, exports do OpenStreetMap e releases governamentais de fronteiras default para GeoJSON quando miram usuários web

Se uma ferramenta consegue falar qualquer formato geoespacial, ela quase certamente fala GeoJSON.

Armadilhas em Produção

GeoJSON é tolerante no dia um e intolerante no dia noventa. As armadilhas que pegam os times:

Longitude primeiro. RFC 7946 fixa a ordem como [lon, lat]. Humanos, endereços e a maior parte da documentação escrevem lat, lon. Trocá-los é o bug mais comum de GeoJSON, e seu ponto acaba no oceano errado.

Polygon winding order. RFC 7946 especifica que anéis exteriores devem ser anti-horários e anéis interiores (buracos) horários. Muitos arquivos GeoJSON antigos ignoram isso. Alguns renderizadores não se importam, outros (notavelmente Mapbox GL com polígonos cruzando o antimeridiano) renderizam o polígono como o inverso do que você queria: uma ilha pequena vira um buraco no oceano cobrindo o resto do mundo.

Tratamento de antimeridiano. Geometria cruzando o meridiano 180/-180 precisa ser dividida conforme a spec. Polígonos ingênuos desenhados pelo Pacífico renderizam como uma faixa fina enrolada do lado longo do planeta.

Sem suporte nativo a CRS além de WGS84. RFC 7946 deliberadamente removeu o member crs antigo. Se seus dados estão em uma grade nacional (British National Grid, RD New, EPSG:3857), você precisa reprojetar para WGS84 antes de serializar. Ferramentas que emitem GeoJSON não-WGS84 são tecnicamente não-conformes.

Tamanho de arquivo. Uma FeatureCollection com milhões de polígonos detalhados pode inflar para gigabytes. Para entrega no browser, mude para vector tiles, simplifique geometria com Douglas-Peucker, ou faça stream com GeoJSON delimitado por newline (.ndjson).

Validação. Use um linter como GeoJSONLint ou a biblioteca geojson-validation no CI. Pegar winding order inválida ou coordenadas trocadas em build time é mais barato do que pegar em um ticket de cliente.

GeoJSON no MapAtlas

GeoJSON é o formato padrão de troca de dados em toda a plataforma MapAtlas. O produto Dynamic Maps aceita fontes GeoJSON diretamente para overlays customizados, styling e camadas interativas, sem pré-processamento necessário.

A Geocoding API retorna endereços matched como Features GeoJSON, então um resultado de forward geocode pode ser jogado direto em um mapa ou armazenado no PostGIS sem remapear campos. A Isochrone API retorna áreas de tempo de viagem como polígonos GeoJSON, o que significa que uma query de "lugares alcançáveis em 15 minutos" está a um fetch e uma chamada de addSource de estar na tela.

GeoJSON não é glamouroso. É um subset pequeno e opinativo de JSON com uma ordem fixa de coordenadas e um punhado de tipos de geometria. Mas é o formato que permite a cada camada de uma stack moderna de localização, do banco espacial ao canvas do mapa, concordar sobre o que é um lugar. Acerte a ordem da longitude, valide o winding, e o resto da stack tende a se cuidar sozinho.