You're viewing version 2.17 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
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
:
PUT testindex1
{
"mappings": {
"properties": {
"point": {
"type": "geo_point"
}
}
}
}
Index a geopoint, specifying its latitude and longitude:
PUT testindex1/_doc/1
{
"point": {
"lat": 74.00,
"lon": 40.71
}
}
Search for documents whose point
objects are within the specified distance
from the specified point
:
GET /testindex1/_search
{
"query": {
"bool": {
"must": {
"match_all": {}
},
"filter": {
"geo_distance": {
"distance": "50mi",
"point": {
"lat": 73.5,
"lon": 40.5
}
}
}
}
}
}
The response contains the matching document:
{
"took": 5,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 1,
"hits": [
{
"_index": "testindex1",
"_id": "1",
"_score": 1,
"_source": {
"point": {
"lat": 74,
"lon": 40.71
}
}
}
]
}
}
Parameters
Geodistance queries accept the following parameters.
Parameter | Data type | Description |
---|---|---|
_name | String | The name of the filter. Optional. |
distance | String | The 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_type | String | Specifies 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_method | String | The 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_unmapped | Boolean | Specifies 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.