Geodistance query

A geodistance query returns documents with geopoints that are within a specified distance from the provided geopoint. A document with multiple geopoints matches the query if at least one geopoint matches the query.

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": 74.00,
  5.     "lon": 40.71
  6.   }
  7. }

copy

Search for documents whose point objects are within the specified distance from the specified point:

  1. GET /testindex1/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": {
  6.         "match_all": {}
  7.       },
  8.       "filter": {
  9.         "geo_distance": {
  10.           "distance": "50mi",
  11.           "point": {
  12.             "lat": 73.5,
  13.             "lon": 40.5
  14.           }
  15.         }
  16.       }
  17.     }
  18.   }
  19. }

copy

The response contains the matching document:

  1. {
  2.   "took": 5,
  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": 74,
  24.             "lon": 40.71
  25.           }
  26.         }
  27.       }
  28.     ]
  29.   }
  30. }

Parameters

Geodistance queries accept the following parameters.

ParameterData typeDescription
_nameStringThe name of the filter. Optional.
distanceStringThe distance within which to match the points. This distance is the radius of a circle centered at the specified point. For supported distance units, see Distance units. Required.
distance_typeStringSpecifies how to calculate the distance. Valid values are arc or plane (faster but inaccurate for long distances or points close to the poles). Optional. Default is arc.
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.