WARNING: Version 2.4 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.4] ›Mapping ›Field datatypes

Geo-point datatype

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

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:

geohash

Should the geo-point also be indexed as a geohash in the .geohash sub-field? Defaults to false, unless geohash_prefix is true. [2.4] Deprecated in 2.4.

geohash_precision

The maximum length of the geohash to use for the geohash and geohash_prefix options. [2.4] Deprecated in 2.4.

geohash_prefix

Should the geo-point also be indexed as a geohash plus all its prefixes? Defaults to false. [2.4] Deprecated in 2.4.

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). [2.3] Deprecated in 2.3.

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 »