WARNING: Version 2.2 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

› › ›

Geo-point datatype

edit

Geo-point datatype

edit

Fields of type geo_point accept latitude-longitude pairs, which can be used:

to find geo-points within a bounding box, within a certain distance of a central point, within a polygon, or within a geohash cell.
to aggregate documents by geographically or by distance from a central point.
to integrate distance into a document’s relevance score.
to sort documents by distance.

Percolating geo-queries in Elasticsearch 2.2.0 or later

The new geo_point fields added in Elasticsearch 2.2.0 and above require that doc_values are enabled in order to function. Unfortunately, the in-memory index used by the percolator does not yet have support for doc_values, meaning that geo-queries will not work in a percolator index created in Elasticsearch 2.2.0 or later.

See Percolating geo-queries in Elasticsearch 2.2.0 and later for a workaround.

There are four ways that a geo-point may be specified, as demonstrated below:

PUT my_index
{
  "mappings": {
    "my_type": {
      "properties": {
        "location": {
          "type": "geo_point"
        }
      }
    }
  }
}

PUT my_index/my_type/1
{
  "text": "Geo-point as an object",
  "location": { 
    "lat": 41.12,
    "lon": -71.34
  }
}

PUT my_index/my_type/2
{
  "text": "Geo-point as a string",
  "location": "41.12,-71.34" 
}

PUT my_index/my_type/3
{
  "text": "Geo-point as a geohash",
  "location": "drm3btev3e86" 
}

PUT my_index/my_type/4
{
  "text": "Geo-point as an array",
  "location": [ -71.34, 41.12 ] 
}

GET my_index/_search
{
  "query": {
    "geo_bounding_box": { 
      "location": {
        "top_left": {
          "lat": 42,
          "lon": -72
        },
        "bottom_right": {
          "lat": 40,
          "lon": -74
        }
      }
    }
  }
}

	Geo-point expressed as an object, with `lat` and `lon` keys.
	Geo-point expressed as a string with the format: `"lat,lon"`.
	Geo-point expressed as a geohash.
	Geo-point expressed as an array with the format: [ `lon`, `lat`]
	A geo-bounding box query which finds all geo-points that fall inside the box.

Geo-points expressed as an array or string

Please note that string geo-points are ordered as lat,lon, while array geo-points are ordered as the reverse: lon,lat.

Originally, lat,lon was used for both array and string, but the array format was changed early on to conform to the format used by GeoJSON.

Parameters for `geo_point` fields

edit

The following parameters are accepted by geo_point fields:

`coerce`	Normalize longitude and latitude values to a standard -180:180 / -90:90 coordinate system. Accepts `true` and `false` (default).
`doc_values`	Should the field be stored on disk in a column-stride fashion, so that it can later be used for sorting, aggregations, or scripting? Accepts `true` (default) or `false`.
`geohash`	Should the geo-point also be indexed as a geohash in the `.geohash` sub-field? Defaults to `false`, unless `geohash_prefix` is `true`.
`geohash_precision`	The maximum length of the geohash to use for the `geohash` and `geohash_prefix` options.
`geohash_prefix`	Should the geo-point also be indexed as a geohash plus all its prefixes? Defaults to `false`.
`ignore_malformed`	If `true`, malformed geo-points are ignored. If `false` (default), malformed geo-points throw an exception and reject the whole document.
`lat_lon`	Should the geo-point also be indexed as `.lat` and `.lon` sub-fields? Accepts `true` and `false` (default).
`precision_step`	Controls the number of extra terms that are indexed for each lat/lon point. Defaults to `16`. Ignored if `lat_lon` is `false`.

Using geo-points in scripts

edit

When accessing the value of a geo-point in a script, the value is returned as a GeoPoint object, which allows access to the .lat and .lon values respectively:

geopoint = doc['location'].value;
lat      = geopoint.lat;
lon      = geopoint.lon;

For performance reasons, it is better to access the lat/lon values directly:

lat      = doc['location'].lat;
lon      = doc['location'].lon;

« Date datatype Geo-Shape datatype »

Geo-point datatype

Geo-point datatype

Parameters for geo_point fields

Using geo-points in scripts

Parameters for `geo_point` fields