Elasticsearch Elasticsearch Geo Bounding Box

By Opster Team

Updated: Aug 31, 2023

| 2 min read

Quick links

• Basic usage
• Advanced options
• Accepted formats

Introduction

Elasticsearch provides a robust set of tools for dealing with geospatial data. One of these tools is the Geo Bounding Box query, which allows you to search for documents with geo-points that fall within a specified bounding box. This query is particularly useful when you need to find data within a certain geographical area, such as a city, state, or country.

Basic usage of the Geo Bounding Box Query

The Geo Bounding Box query uses the “geo_bounding_box” query, followed by the field name containing the geo-point data. The bounding box is defined by its top-left and bottom-right corners, each specified as a pair of latitude and longitude coordinates.

Here’s a basic example of a Geo Bounding Box query:

GET /_search
{
  "query": {
    "geo_bounding_box": {
      "location": {
        "top_left": {
          "lat": 40.73,
          "lon": -74.1
        },
        "bottom_right": {
          "lat": 40.01,
          "lon": -71.12
        }
      }
    }
  }
}

In this example, “location” is the field containing the geo-point data, and the bounding box is defined by the coordinates (40.73, -74.1) for the top-left corner and (40.01, -71.12) for the bottom-right corner.

Advanced options for the Geo Bounding Box Query

The Geo Bounding Box query also supports several options that can be used to fine-tune the query. For example, you can use the “validation_method” option to control how the query handles invalid bounding boxes. By default, the query will throw an exception if the bounding box is invalid. However, you can set “validation_method” to “IGNORE_MALFORMED” to ignore invalid bounding boxes, or “COERCE” to adjust the bounding box to make it valid.

Here’s an example of a Geo Bounding Box query with the “validation_method” option:

GET /_search
{
  "query": {
    "geo_bounding_box": {
      "location": {
        "top_left": {
          "lat": 40.73,
          "lon": -74.1
        },
        "bottom_right": {
          "lat": 40.01,
          "lon": -71.12
        }
      },
      "validation_method": "COERCE"
    }
  }
}

Accepted formats

In order to accommodate most use cases, the Geo Bounding Box query accepts the top-left and bottom-right geo-points to be specified in different formats than the one presented above. The table below enumerates all supported formats for specifying the bounding box:

Finally, instead of specifying only the top-left and bottom-right geo-points, it is also possible to specify each vertices individually, as shown below:

GET /_search
{
  "query": {
    "geo_bounding_box": {
      "location": {
        "top": 40.73,
        "left": -74.1,
        "bottom": 40.01,
        "right": -71.12
      }
    }
  }
}