Geo-bounding box queries

    You can use a geo-bounding box query to search for documents that contain geopoints.

    Create a mapping with the field mapped as geo_point:

    Index three geopoints as objects with latitudes and longitudes:

    1. PUT testindex1/_doc/1
    2. {
    3.   "point": { 
    4.     "lat": 74.00,
    5.     "lon": 40.71
    6.   }
    7. }
    9. PUT testindex1/_doc/2
    10. {
    11.   "point": { 
    12.     "lat": 72.64,
    13.     "lon": 22.62
    14.   } 
    15. }
    17. PUT testindex1/_doc/3
    18. {
    19.   "point": { 
    20.     "lat": 75.00,
    21.   }
    22. }

    Search for all documents and filter the documents whose points lie within the rectangle defined in the query:

    1. {
    2.   "took" : 20,
    3.   "timed_out" : false,
    4.   "_shards" : {
    5.     "total" : 1,
    6.     "successful" : 1,
    7.     "skipped" : 0,
    8.     "failed" : 0
    10.   "hits" : {
    11.     "total" : {
    12.       "value" : 1,
    13.       "relation" : "eq"
    14.     },
    15.     "max_score" : 1.0,
    16.     "hits" : [
    17.       {
    18.         "_index" : "testindex1",
    19.         "_id" : "1",
    20.         "_score" : 1.0,
    21.         "_source" : {
    22.           "point" : {
    23.             "lat" : 74.0,
    24.             "lon" : 40.71
    25.         }
    26.       }
    27.     ]
    28.   }
    29. }

    The preceding response does not include the document with a geopoint of "lat": 75.00, "lon": 28.00 because of the geopoint’s limited .

    Geopoint coordinates are always rounded down at index time. At query time, the upper boundaries of the bounding box are rounded down, and the lower boundaries are rounded up. Therefore, the documents with geopoints that lie on the lower and left edges of the bounding box might not be included in the results due to rounding error. On the other hand, geopoints that lie on the upper and right edges of the bounding box might be included in the results even though they are outside the boundaries. The rounding error is less than 4.20 × 10−8 degrees for latitude and less than 8.39 × 10−8 degrees for longitude (around 1 cm).

    You can specify the bounding box by providing any of the following combinations of its vertex coordinates:

    • top_left and bottom_right
    • top_right and bottom_left
    • top, left, bottom, and right

    The following example shows how to specify the bounding box using the top, left, , and right coordinates:

    You can specify coordinates of the bounding box vertices in any format that the geopoint field type accepts.

    If you use a geohash to specify the bounding box, the geohash is treated as a rectangle. The upper-left vertex of the bounding box corresponds to the upper-left vertex of the top_left geohash, and the lower-right vertex of the bounding box corresponds to the lower-right vertex of the bottom_right geohash.

    The following example shows how to use a geohash to specify the same bounding box as the previous examples:

    1. GET testindex1/_search
    2. {
    3.   "query": {
    4.     "bool": {
    5.       "must": {
    6.         "match_all": {}
    7.       },
    8.       "filter": {
    9.         "geo_bounding_box": {
    10.           "point": {
    11.             "top_left": "ut7ftjkfxm34",
    12.             "bottom_right": "uuvpkcprc4rc"
    13.           }
    14.         }
    15.       }
    16.     }
    17.   }
    18. }

    To specify a bounding box that covers the whole area of a geohash, provide that geohash as both top_left and parameters of the bounding box: