Catalog My learning Blog
Elasticsearch Tutorial: How Full-Text Search Works · Phase 3 · Lesson 20 · 3 min read

Elasticsearch Geo Queries and Distance Search

On this page
  1. Geo search: open late, near me
  2. geo_point and geo_shape mappings
  3. Example: a store finder with geo_distance and sorting
  4. geo_bounding_box, geo_shape and distance decay scoring
  5. Geo aggregations for map clusters
  6. Practical notes for geo search
  7. Check yourself

Geo search: open late, near me

A store finder needs stores within a few kilometers of the user, still open, nearest first. Elasticsearch handles location as a first-class field type, combinable with any other query.

geo_point and geo_shape mappings

HTTP
PUT /stores
{ "mappings": { "properties": {
    "name":      { "type": "text" },
    "location":  { "type": "geo_point" },
    "open_late": { "type": "boolean" } } } }

A geo_point accepts {"lat": 51.5136, "lon": -0.1365}, a "lat,lon" string, or GeoJSON [lon, lat] arrays. Watch the order: GeoJSON and arrays put longitude first, a common source of points landing in the ocean. For areas (delivery zones, regions), use geo_shape.

Example: a store finder with geo_distance and sorting

Five stores: four in London, one in Brighton. Open-late stores within 5 km of Covent Garden, nearest first:

HTTP
GET /stores/_search
{
  "query": { "bool": { "filter": [
    { "geo_distance": { "distance": "5km", "location": { "lat": 51.5117, "lon": -0.1240 } } },
    { "term": { "open_late": true } } ] } },
  "sort": [ { "_geo_distance": {
    "location": { "lat": 51.5117, "lon": -0.1240 }, "order": "asc", "unit": "km" } } ]
}
Code
  Soho         0.89 km
  Camden       3.30 km
  • Shoreditch is 3.6 km away but not open late: filtered out.
  • Greenwich is open late but 8.7 km away: outside the radius.
  • Brighton is 77 km away.
  • Each hit's sort value is its distance, ready to display.

Distance and other location conditions are yes/no, so they go in filter (Day 12).

Stores are filtered to a radius around the user, combined with other conditions, and sorted by distance; geo aggregations group points into grid cells for map displays.
Stores are filtered to a radius around the user, combined with other conditions, and sorted by distance; geo aggregations group points into grid cells for map displays.

geo_bounding_box, geo_shape and distance decay scoring

  • geo_bounding_box: everything inside the visible map rectangle. Fast; use it when the user pans a map.
  • geo_shape: points inside a polygon (a delivery zone, a city boundary), or shapes that intersect.
  • Distance decay scoring: with function_score and gauss on the location (Day 10), nearer results score higher without a hard cutoff, mixed with text relevance: "pizza near me" balances how good the match is with how close it is.

Geo aggregations for map clusters

  • geotile_grid and geohash_grid group points into grid cells for heat maps and clusters at any zoom level.
  • geo_distance aggregation counts results in distance rings: within 1 km, 1 to 5 km, 5 to 10 km.
  • geo_bounds and geo_centroid compute the area covering the results and their center, for fitting a map view.
  • Distances use a sphere approximation (arc by default); fine for store finders, not surveying.
  • Store coordinates with sensible precision: five decimal places is about a meter.
  • Combine geo filters with text and business rules freely; filter first, then score.

Check yourself

The query also filtered on open_late, and Shoreditch isn't open late. All filters in a bool query must match, so distance alone wasn't enough.

Putting latitude first. GeoJSON and Elasticsearch's array form use [longitude, latitude], so swapped values put points somewhere else entirely, often in the ocean. The object form { "lat": ..., "lon": ... } avoids the confusion.

Use a decay function, such as gauss, on the location inside function_score, so scores fall off smoothly with distance while text relevance still counts.

When documents are areas or lines, like delivery zones, and you need queries such as which zone contains this address.

geotile_grid or geohash_grid group points into map cells, so a map shows clusters with counts instead of thousands of markers.