Um bounding box é o primitivo espacial mais simples e útil em qualquer stack de mapeamento. São quatro números que descrevem um retângulo no espaço de latitude e longitude, e ele aparece em quase toda chamada de API, arquivo GeoJSON e biblioteca de mapas que você vai usar.
Este guia explica o que é um bounding box, as convenções de formato que você precisa conhecer, os padrões de produção onde ele brilha e as armadilhas que todo desenvolvedor cai pelo menos uma vez.
A Definição
Um bounding box (bbox) é o menor retângulo alinhado aos eixos que contém uma feature ou um conjunto de pontos. "Alinhado aos eixos" significa que seus lados correm ao longo dos eixos de latitude e longitude; o retângulo não está rotacionado. O bbox é descrito por quatro números: a longitude oeste, a latitude sul, a longitude leste e a latitude norte.
Para Paris, o bbox municipal oficial é aproximadamente [2.224, 48.8156, 2.4699, 48.9022]. Para a França continental é aproximadamente [-5.142, 41.333, 9.560, 51.089]. Para o planeta inteiro é [-180, -90, 180, 90].
Um bbox é sempre dois cantos opostos. Não consegue descrever uma forma não retangular, mas consegue descrever o retângulo que envolve qualquer forma, o que é suficiente para filtragem espacial rápida.
A Questão do Formato
As convenções de formato para bbox são inconsistentes entre sistemas, e essa inconsistência é a fonte da maioria dos bugs de bbox.
GeoJSON, padrões OGC e a maioria das APIs modernas: [west, south, east, north], equivalentemente [minLng, minLat, maxLng, maxLat]. Longitude primeiro, latitude segundo, ambas em WGS84.
Algumas bibliotecas de mapeamento web (objetos LatLngBounds do Leaflet, Mapbox GL): um objeto LatLngBounds com cantos _southWest e _northEast. Lat primeiro, depois lng.
Muitas APIs mais antigas e exportações CSV: [south, west, north, east] (lat primeiro). Leia a spec.
Serviços de tiles e WMS: bbox nas unidades da projeção (metros Web Mercator, não lat/lng) quando o tile está em EPSG:3857.
A regra defensiva: nunca use um array simples de 4 elementos no seu próprio código. Envolva-o em um objeto tipado com campos nomeados ({ west, south, east, north }) para que a ordem seja explícita. Converta nas fronteiras da API.
Onde Bounding Boxes Mostram Seu Valor
Um bbox é o filtro espacial mais rápido possível. Três usos clássicos:
Ajustar um mapa a uma feature. Quando o usuário chega a um resultado de busca, você chama map.fitBounds(bbox) e o mapa faz zoom e pan para mostrar a feature com padding adequado. Toda biblioteca de mapas moderna tem esse primitivo.
Filtrar consultas de API por área. Mecanismos de banco de dados e APIs de busca indexam bboxes de forma muito eficiente. Uma consulta como "mostre todos os lugares neste viewport" envia o bbox visível para o servidor, que usa um índice espacial para retornar apenas os registros correspondentes. Esta é a base da busca baseada em viewport.
Enviesando autocomplete e geocodificação. Passe o bbox atual do mapa do usuário como viés de viewport. O geocodificador pondera os resultados dentro do bbox mais pesadamente, para que digitar "Liberdade" dentro do viewport de São Paulo retorne o bairro Liberdade antes de qualquer outra Liberdade no mundo.
Um quarto uso, menos óbvio: bboxes são a unidade de contabilidade de um sistema de vector tiles. Cada tile cobre um bbox conhecido em um zoom conhecido, e o renderizador os compõe no mapa visível.
O Que uma API Retorna
A maioria das APIs de geocodificação retorna um bbox junto com cada correspondência, porque isso indica tanto o tamanho da feature correspondida (um bbox de país é enorme, um bbox de prédio é minúsculo) quanto como ajustar o mapa. Uma resposta de geocodificação para "França" retorna um bbox em escala nacional; uma resposta para "10 Downing Street" retorna um bbox em escala de prédio.
Você pode usar o tamanho do bbox retornado como verificação de sanidade na precisão. Uma consulta que corresponde em precisão de "país" mas retorna um bbox do tamanho de um prédio é suspeita. Uma consulta que corresponde em precisão de "telhado" mas retorna um bbox do tamanho de uma cidade está quebrada.
Bounding Boxes que Cruzam o Antimeridiano
Uma armadilha sutil: um bbox que cruza o antimeridiano de 180 graus (ex: para a Rússia, o Pacífico, Fiji) não pode ser descrito como west < east porque dá a volta. As convenções variam:
- Alguns sistemas dividem esse bbox em duas partes, uma para cada lado do antimeridiano.
- Alguns sistemas permitem
west > easte interpretam como "dar a volta". - GeoJSON permite dar a volta mas recomenda dividir para interoperabilidade.
Para a maioria dos casos de uso europeus ou de país único, isso nunca acontece. Se você construir um produto global (rotas aéreas, transporte marítimo, pesca), teste o caso do antimeridiano explicitamente.
Bounding Boxes vs Polígonos
Um bbox é um retângulo. Uma feature real raramente é retangular. O bbox da França inclui partes do Oceano Atlântico e da Espanha. O bbox de Manhattan inclui partes de Nova Jersey e Queens.
Quando a aproximação retangular é boa o suficiente (ajustar um mapa, pré-filtragem rápida), o bbox é a ferramenta certa. Quando você precisa saber se um ponto está realmente dentro da feature, precisa de matemática de ponto-em-polígono contra a geometria de limite real. Um padrão comum de produção: filtre por bbox primeiro (rápido, indexável, elimina 99% dos registros), depois execute ponto-em-polígono nos sobreviventes (lento mas preciso). Essa abordagem em dois estágios é como a maioria dos bancos de dados espaciais funciona internamente.
Bounding Boxes em Visão Computacional
Você pode ver "oriented bounding box" mencionado em detecção de objetos, robótica ou renderização 3D. É um conceito diferente: um OBB é rotacionado para se ajustar a uma feature mais firmemente do que um box alinhado aos eixos faria. No trabalho geoespacial, bboxes alinhados aos eixos são o padrão porque se indexam de forma limpa, se encaixam na grade de tiles e são triviais para testar sobreposição. Oriented bboxes aparecem quando você precisa de matemática de retângulo rotacionado, o que é raro no mapeamento mas comum em visão computacional.
Como o MapAtlas Usa Bounding Boxes
Todos os resultados da Geocoding API e da Search API retornam um campo bbox com a extensão da feature correspondida na ordem longitude/latitude WGS84, exatamente o formato que GeoJSON e bibliotecas de mapas modernas esperam. Você pode passar um parâmetro boundary.rect.* para enviesar a geocodificação para um viewport, e a Isochrone API retorna seus polígonos de tempo de viagem com um bbox envolvente para que você possa ajustar um mapa sem calculá-lo por conta própria.
Para uma introdução prática ao GeoJSON e como bboxes se encaixam no quadro maior de dados espaciais, veja O Que É GeoJSON e O Que É um Geocode.
Perguntas frequentes
O que é um bounding box?
Um bounding box (muitas vezes abreviado como bbox) é o menor retângulo alinhado aos eixos que contém uma feature geográfica ou um conjunto de pontos. É descrito por quatro números: a longitude mínima e máxima e a latitude mínima e máxima. Bounding boxes são usados em todo lugar no mapeamento: para ajustar um mapa a uma feature, para filtrar consultas de banco de dados por área, para definir a extensão de um tile e para enviesar resultados de geocodificação para uma região. São o primitivo espacial mais simples e rápido no código de produção.
Qual é o formato padrão para um bounding box?
GeoJSON e a maioria das APIs modernas usam a ordem [west, south, east, north], também escrita como [minLng, minLat, maxLng, maxLat]. Este é o formato que você deve usar como padrão. Algumas APIs mais antigas e exportações CSV usam [south, west, north, east] (ou seja, lat primeiro), e algumas usam quatro campos separados. Sempre verifique a documentação da API ou formato específico. O erro mais comum é misturar a ordem lat/lng, o que coloca o box no lado errado do planeta.
Qual é a diferença entre um bounding box e um oriented bounding box?
Um bounding box regular é alinhado aos eixos: seus lados correm ao longo dos eixos de latitude e longitude. Um oriented bounding box (OBB, comum em visão computacional e motores de jogos) é rotacionado para se ajustar mais firmemente à feature, o que dá uma área menor mas matemática mais complexa. No trabalho geoespacial, bboxes alinhados aos eixos são o padrão porque se indexam de forma limpa em bancos de dados espaciais, se encaixam na grade de tiles e são trivialmente testáveis para sobreposição. Oriented bounding boxes aparecem em renderização 3D, detecção de objetos e motores de física.
Como uso um bounding box para filtrar uma API de geocodificação?
Passe o bbox como parâmetro de viés de viewport. Na MapAtlas Geocoding API você envia `boundary.rect.min_lon`, `boundary.rect.min_lat`, `boundary.rect.max_lon`, `boundary.rect.max_lat`, e o geocodificador classifica os resultados dentro dessa área mais alto do que os resultados fora dela. Isso é essencial para autocomplete dentro de um mapa: conforme o usuário faz pan, você atualiza o bbox para que as sugestões correspondam ao que ele está vendo. Sem um viés de bbox, um autocomplete para 'Springfield' retorna qualquer Springfield que tenha a maior popularidade global, que raramente é o que o usuário quer dizer.
