Elasticsearch in Action: The geo_distance Query

Excerpts taken from my upcoming book: Elasticsearch in Action

The excerpts are taken from my book Elasticsearch in Action, Second Edition. The code is available in my GitHub repository. You can find executable Kibana scripts in the repository so you can run the commands in Kibana straight away. All code is tested against Elasticsearch 8.4 version.

Me @ Medium || LinkedIn || Twitter || GitHub

In the last article, we discussed about geo_bounding_box query. This article is all about geo_distance query. In the next article, we look at geo_shape query.

Overview

When we want to find a list of addresses surrounding a central point, the geo_distancequery comes in handy. It works by circling an area with a radius of a given distance from a focal point. For example, as the figure below shows, we may want to find nearby schools in the vicinity of a 10 km radius.

Figure : Returning schools with a geo_distance query

Let’s look at the geo_distancequery in action. The following listing defines a geo_distancequery that fetches all the restaurants within 175 km from the given central coordinates.

Listing : Searching for restaurants within a given radius

GET restaurants/_search
{
  "query": {
    "geo_distance": {
      "distance": "175 km",
      "location": { 
        "lat": 50.00,
        "lon": 0.10
      }
    }
  }
}

As the listing shows, the geo_distancequery expects two attributes: the distance attribute, which provides the radius of the geocircle, and the geo field location, which defines the central point of the geocircle. The query returns all the restaurants that are 175 km from the defined point.

Note: The distance field accepts the distance measured in kilometers or miles provided as km or mi, respectfully. For example, Elasticsearch honors the value given as “350 mi” as well as “350mi” (with the space removed).

It shouldn’t surprise you if I tell you that the field for defining the central point can be input using the latitude and longitude in the form of strings, arrays, WKT, and other formats. The queries can also be run on geoshapes too, though I will leave it to you to experiment with them.

The geo_bounding_boxand geo_distancequeries cater for searching our addresses represented as point-based locations in rectangular shapes and circles. However, we often require searching for an address defined as a shape inside another shape, preferably a polygonal shape. This is where we use a geo_shapequery, discussed in the following section.

In the last article, we discussed about geo_bounding_box query. This article is all about geo_distance query. In the next article, we look at geo_shape query.

Me @ Medium || LinkedIn || Twitter || GitHub

These short articles are condensed excerpts taken from my book Elasticsearch in Action, Second Edition. The code is available in my GitHub repository.

Elasticsearch in Action