A bounding box is an envelope — [west, south, east, north] — that
describes the extent of a map viewport or a query's search bounds. It is
not a shape describing any real place: nothing about a store's coverage or
a region's outline is naturally rectangular, and a bounding box used as a
targeting or reporting geometry is almost always a stand-in for
"everything visible on screen right now" or "everything the caller asked to
search within," not a deliberate footprint. Treating a bounding box as if
it carries the same intent as a drawn polygon is the family's core
conceptual risk; treating it as a trivial four-number rectangle with no
edge cases is the family's core implementation risk.
- Cardinality
- One rectangle — never a partition, never a real footprint
- Governed by
- Whatever client or query produced it — a viewport state or search parameter
- Not a geometry
- A saved market label attached to a live, constantly-changing viewport rectangle
- Converts via
- Corner-to-polygon construction (antimeridian-aware), then polyfill
Members
| Member | What it bounds | Typical origin |
|---|---|---|
| Map viewport | The currently visible map extent | Client-side map state (pan/zoom) |
| Search bounds | A geocoder or places-API query restriction | API request parameter |
| API query envelope | A spatial filter on a data query | Query parameter |
| Market extent | A rough rectangular stand-in for a market's footprint | Manually specified, often for a quick estimate |
Required metadata
| Field | Why it's required |
|---|---|
| CRS | Standard EPSG:4326 assumption, but verify — some mapping SDKs report viewport bounds in Web Mercator |
| Screen vs. geographic | A screen-space rectangle and a true geographic envelope are easy to conflate but behave differently near the poles and the antimeridian |
| Coordinate order convention | [west, south, east, north] is one common convention; [minLng, minLat, maxLng, maxLat] is numerically identical but callers still transpose lat/lng within it |
Common risks
Antimeridian crossing: when a box crosses ±180° longitude, west is
numerically greater than east (e.g. west=170, east=-170 for a box
spanning the ±180° line near Fiji) — a naive box-to-polygon conversion that
assumes west < east either produces an inverted rectangle or, worse, a
box that silently spans the entire globe the wrong way. This is common
enough near the Pacific that any bounding-box conversion needs an explicit
antimeridian check, not an assumption that it won't happen; see
antimeridian handling. Rotated boxes:
some viewport-derived bounds are not axis-aligned (a rotated map view), and
a [west, south, east, north] tuple cannot represent rotation at all —
if the source system supports rotation, the bounding box handed to a
conversion may already be a lossy axis-aligned approximation of the true
viewport, and that loss should be disclosed rather than treated as exact.
Screen vs. geographic conflation: a screen/viewport rectangle changes
with every pan and zoom and is not a stable geometry to persist or report
against, while a geographic envelope (a market extent, a search radius
expressed as a box) is meant to be stable; using a live viewport bound as
if it were a saved market definition silently changes the "region" every
time a user's map state changes. West/east ordering assumptions:
distinct from the antimeridian case, some upstream systems deliver bounds
already reordered (min/max rather than west/east), and assuming the
tuple order matches the field names without checking produces a box that
is numerically valid but geographically wrong.
A market extent expressed as a bounding box is a rectangle that happens to contain the market, not a shape describing it — it will always include territory the market doesn't actually cover. Where a real market footprint is needed rather than a quick rectangular estimate, use arbitrary polygons or administrative boundaries instead.
How it converts to H3
A bounding box converts to H3 by first constructing a four-vertex polygon from its corners — handling the antimeridian sign flip explicitly — and then polyfilling that polygon under the same containment modes used for any other polygon. See bounding box to H3 for the corner-construction algorithm and the antimeridian-safe splitting logic, and coordinate and CRS failures for the broader class of ordering and projection mistakes that a bounding box is especially prone to surfacing, since a four-number rectangle offers no redundancy to catch a transposed coordinate the way a denser polygon ring sometimes does.