Geo-bounding-box query #

Matches documents whose geo_point field falls inside a rectangle defined by its top-left and bottom-right corners. Coordinates are WGS-84 degrees; filtering only (does not contribute distance scoring).

It is the cheapest geographic filter. When the region you need is a rectangle of latitude and longitude — a map viewport, a city’s extents, a country’s outline approximated by its bounds — the engine answers with a single index range and no per-document geometry math.

How it works #

A geo_point field is indexed as a two-dimensional BKD tree keyed by (lat, lon). At ingest a point may arrive in any of three forms — the object {"lat": .., "lon": ..}, the array [lon, lat] (longitude first), or the string "lat,lon" — all normalized to the same pair before they reach the tree.

The query is that tree’s range. The walk visits only leaves between (bottom_right_lat, top_left_lon) and (top_left_lat, bottom_right_lon), and every document in a visited leaf matches — the rectangle is the index predicate itself, so there is no second verification phase. Results are exact, with points on all four edges included.

The box must have its west edge at or left of its east edge (top_left_lon <= bottom_right_lon); a box that would cross the antimeridian is not split into two — issue two queries joined by a bool should instead.

The nested form is accepted too and rewritten at the gateway: {"geo_bounding_box": {"location": {"top_left": <pt>, "bottom_right": <pt>}}} with each corner in any of the three point forms. Options such as validation_method are accepted for compatibility and ignored.

Examples #

The live query frames a box over eastern China — latitude 30–42, longitude 116–123. Five of the fifteen places match: the two Beijing places, the two Shanghai places and the Hangzhou store.

POST /my-collection/_search
{
  "query": {
    "geo_bounding_box": {
      "field": "location",
      "top_left_lat": 40.73,
      "top_left_lon": -74.1,
      "bottom_right_lat": 40.01,
      "bottom_right_lon": -71.12
    }
  }
}

Use cases #

• Map viewport search. “Everything inside the rectangle the user is looking at” is the canonical bounding-box question — one range per pan or zoom, served straight from the BKD tree.
• Rectangular geofencing. Alerting or access rules tied to a box (a warehouse district, a no-fly rectangle) filter with this query before any scoring happens.
• Cheap prefilter for expensive stages. Narrow a large index by area first, then aggregate or score the survivors — the box costs one tree range, so it composes well inside a bool filter.
• Coverage checks. Which of our stores fall inside the region’s bounding box — a quick audit before finer tools such as geo_polygon trim the corners.

Parameters for geo_bounding_box #

• field
  (Required, string) The geo_point field to filter on.
• top_left_lat
  (Required, number) Top-left corner latitude (north edge).
• top_left_lon
  (Required, number) Top-left corner longitude (west edge).
• bottom_right_lat
  (Required, number) Bottom-right corner latitude (south edge).
• bottom_right_lon
  (Required, number) Bottom-right corner longitude (east edge).

The four corners are plain numbers; both the flat form above and the nested form (corners as point objects) deserialize into the same query.

Related #

• geo_distance — round regions: everything within a great-circle radius of one centre point.
• geo_polygon — arbitrary rings, when the region’s corners matter.
• geo_shape — full geometries indexed per document and tested against a query shape.
• geo-distance aggregation — after filtering, bucket the survivors by distance rings.
• geo-centroid aggregation — the mean centre of the matched points.