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.

« Date datatype Geo-Shape datatype »
Elastic Docs ›Elasticsearch Guide [2.2] ›Mapping ›Field datatypes

Geo-point datatype

edit

Geo-point datatype

edit

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

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 »