Geopolygon query

A geopolygon query returns documents containing geopoints that are within the specified polygon. A document containing multiple geopoints matches the query if at least one geopoint matches the query.

A polygon is specified by a list of vertices in coordinate form. Unlike specifying a polygon for a geoshape field, the polygon does not have to be closed (specifying the first and last points at the same is unnecessary). Though points do not have to follow either clockwise or counterclockwise order, it is recommended that you list them in either of these orders. This will ensure that the correct polygon is captured.

The searched document field must be mapped as geo_point.

Example

Create a mapping with the point field mapped as geo_point:

  1. PUT /testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "point": {
  6.         "type": "geo_point"
  7.       }
  8.     }
  9.   }
  10. }

copy

Index a geopoint, specifying its latitude and longitude:

  1. PUT testindex1/_doc/1
  2. {
  3.   "point": { 
  4.     "lat": 73.71,
  5.     "lon": 41.32
  6.   }
  7. }

copy

Search for documents whose point objects are within the specified geo_polygon:

  1. GET /testindex1/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": {
  6.         "match_all": {}
  7.       },
  8.       "filter": {
  9.         "geo_polygon": {
  10.           "point": {
  11.             "points": [
  12.               { "lat": 74.5627, "lon": 41.8645 },
  13.               { "lat": 73.7562, "lon": 42.6526 },
  14.               { "lat": 73.3245, "lon": 41.6189 },
  15.               { "lat": 74.0060, "lon": 40.7128 }
  16.            ]
  17.           }
  18.         }
  19.       }
  20.     }
  21.   }
  22. }

copy

The polygon specified in the preceding request is the quadrilateral depicted in the following image. The matching document is within this quadrilateral. The coordinates of the quadrilateral vertices are specified in (latitude, longitude) format.

Search for points within the specified quadrilateral

The response contains the matching document:

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

In the preceding search request, you specified the polygon vertices in clockwise order:

  1. "geo_polygon": {
  2.     "point": {
  3.     "points": [
  4.         { "lat": 74.5627, "lon": 41.8645 },
  5.         { "lat": 73.7562, "lon": 42.6526 },
  6.         { "lat": 73.3245, "lon": 41.6189 },
  7.         { "lat": 74.0060, "lon": 40.7128 }
  8.     ]
  9.     }
  10. }

Alternatively, you can specify the vertices in counterclockwise order:

  1. "geo_polygon": {
  2.     "point": {
  3.     "points": [
  4.         { "lat": 74.5627, "lon": 41.8645 },
  5.         { "lat": 74.0060, "lon": 40.7128 },
  6.         { "lat": 73.3245, "lon": 41.6189 },
  7.         { "lat": 73.7562, "lon": 42.6526 }
  8.     ]
  9.     }
  10. }

The resulting query response contains the same matching document.

However, if you specify the vertices in the following order:

  1. "geo_polygon": {
  2.     "point": {
  3.     "points": [
  4.         { "lat": 74.5627, "lon": 41.8645 },
  5.         { "lat": 74.0060, "lon": 40.7128 },
  6.         { "lat": 73.7562, "lon": 42.6526 },
  7.         { "lat": 73.3245, "lon": 41.6189 }
  8.     ]
  9.     }
  10. }

The response returns no results.

Parameters

Geopolygon queries accept the following parameters.

ParameterData typeDescription
_nameStringThe name of the filter. Optional.
validation_methodStringThe validation method. Valid values are IGNORE_MALFORMED (accept geopoints with invalid coordinates), COERCE (try to coerce coordinates to valid values), and STRICT (return an error when coordinates are invalid). Optional. Default is STRICT.
ignore_unmappedBooleanSpecifies whether to ignore an unmapped field. If set to true, then the query does not return any documents that contain an unmapped field. If set to false, then an exception is thrown when the field is unmapped. Optional. Default is false.

Accepted formats

You can specify the geopoint coordinates when indexing a document and searching for documents in any format accepted by the geopoint field type.