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;