Skip to main content
O que é um bounding box? Guia do BBox em mapas e APIs
Guides

O que é um bounding box? Guia do BBox em mapas e APIs

Um bounding box é o menor retângulo que contém uma feature ou conjunto de pontos. Guia sobre formatos, convenções e armadilhas para trabalhar com bboxes em APIs

Brent van der Heiden6 min read
#bounding box#bbox#geojson#geocodificação#filtro espacial#maps api

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 metropolitana, incluindo a Córsega, é 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.

Leaflet: um objeto LatLngBounds com cantos _southWest e _northEast, lat primeiro, depois lng. Mapbox GL e MapLibre usam LngLatBounds, com lng primeiro.

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 > east e interpretam como "dar a volta".
  • GeoJSON (RFC 7946) permite isso, com oeste maior que leste, enquanto geometrias que cruzam o antimeridiano devem ser cortadas em duas.

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 a maioria 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.

Achou útil? Compartilhe.

Sobre o autor

Brent van der Heiden

Escrito por

Brent van der Heiden

Co-Founder & CEO at MapAtlas

Brent built MapAtlas out of a conviction that developers deserve location APIs with fair pricing and genuine end-user privacy. Before that he co-founded MapMetrics, a community mapping and navigation app. He writes about geospatial infrastructure, map data, AI search visibility, and how location data powers the products people rely on every day.

Ver todos os artigos →
Voltar ao blog