Elasticsearch Elasticsearch Geo Distance

By Opster Team

Updated: Aug 28, 2023

| 2 min read

Introduction

Elasticsearch provides a robust set of tools for dealing with geospatial data. One of the most useful of these is the Geo-Distance query, which allows you to search for documents within a certain distance of a geographical point. This article will delve into the intricacies of the Geo-Distance query, providing examples and step-by-step instructions to help you make the most of this feature.

Understanding Geo-Distance queries

Geo-Distance queries are used to find documents that fall within a specified distance from a geographical point. The point is defined by its latitude and longitude, and the distance can be specified in various units such as kilometers, miles, or even nautical miles.

The basic structure of a Geo-Distance query is as follows:

json
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_distance": {
          "distance": "200km",
          "pin.location": {
            "lat": 40.73,
            "lon": -74.1
          }
        }
      }
    }
  }
}

In this example, the query will return all documents that are within 200 kilometers of the point with latitude 40.73 and longitude -74.1.

Implementing Geo-Distance queries step-by-step

Step one: Index mapping

To implement a Geo-Distance query, you first need to ensure that your index mapping includes a field of type `geo_point`. This field will hold the latitude and longitude values for your documents. Here’s an example of how to define such a field:

json
{
  "mappings": {
    "properties": {
      "pin": {
        "properties": {
          "location": {
            "type": "geo_point"
          }
        }
      }
    }
  }
}

The Geo Distance query also works with fields of type `geo_shape` which can be defined as shown in the mapping below:

json
{
  "mappings": {
    "properties": {
      "pin": {
        "properties": {
          "location": {
            "type": "geo_shape"
          }
        }
      }
    }
  }
}

Step two: Index documents

Once your mapping is set up, you can index documents that include latitude and longitude values. Here’s an example of how to index a document with a `geo_point` field:

json
{
  "pin" : {
    "location" : {
      "lat" : 40.12,
      "lon" : -71.34
    }
  }
}

And here is an example of how to index a document with a `geo_shape` field:

json
{
  "pin" : {
    "location" : {
      "type" : "point",
      "coordinates" : [-71.34, 40.12]
    }
  }
}

Step three: Run Geo-Distance query

With your documents indexed, you can now run Geo-Distance queries against them. The following query, for example, would return all documents within 100 kilometers of the point with latitude 40.12 and longitude -71.34:

json
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_distance": {
          "distance": "100km",
          "pin.location": {
            "lat": 40.12,
            "lon": -71.34
          }
        }
      }
    }
  }
}