Geo-point field type

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, or within a polygon or within a geo_shape query.
• to aggregate documents geographically or by distance from a central point.
• to integrate distance into a document’s relevance score.
• to sort documents by distance.

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

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_point"
      }
    }
  }
}
PUT my-index-000001/_doc/1
{
  "text": "Geo-point as an object",
  "location": { 
    "lat": 41.12,
    "lon": -71.34
  }
}
PUT my-index-000001/_doc/2
{
  "text": "Geo-point as a string",
  "location": "41.12,-71.34" 
}
PUT my-index-000001/_doc/3
{
  "text": "Geo-point as a geohash",
  "location": "drm3btev3e86" 
}
PUT my-index-000001/_doc/4
{
  "text": "Geo-point as an array",
  "location": [ -71.34, 41.12 ] 
}
PUT my-index-000001/_doc/5
{
  "text": "Geo-point as a WKT POINT primitive",
  "location" : "POINT (-71.34 41.12)" 
}
GET my-index-000001/_search
{
  "query": {
    "geo_bounding_box": { 
      "location": {
        "top_left": {
          "lat": 42,
          "lon": -72
        },
        "bottom_right": {
          "lat": 40,
          "lon": -74
        }
      }
    }
  }
}

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.

A point can be expressed as a geohash. Geohashes are base32 encoded strings of the bits of the latitude and longitude interleaved. Each character in a geohash adds additional 5 bits to the precision. So the longer the hash, the more precise it is. For the indexing purposed geohashs are translated into latitude-longitude pairs. During this process only first 12 characters are used, so specifying more than 12 characters in a geohash doesn’t increase the precision. The 12 characters provide 60 bits, which should reduce a possible error to less than 2cm.

Parameters for geo_point fields

The following parameters are accepted by geo_point fields:

Using geo-points in scripts

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:

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

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

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