NOTE: You are looking at documentation for an older release. For the latest information, see the current release documentation.

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

Geo-point datatype

edit

Geo-point datatype

edit

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

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

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

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

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

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

PUT my_index/_doc/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.

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

edit

The following parameters are accepted by geo_point fields:

ignore_malformed

If true, malformed geo-points are ignored. If false (default), malformed geo-points throw an exception and reject the whole document.

ignore_z_value

If true (default) three dimension points will be accepted (stored in source) but only latitude and longitude values will be indexed; the third dimension is ignored. If false, geo-points containing any more than latitude and longitude (two dimensions) values throw an exception and reject the whole document.

index

Should the field be searchable? Accepts true (default) and false.

null_value

Accepts an geopoint value which is substituted for any explicit null values. Defaults to null, which means the field is treated as missing.

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:

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;
« Date datatype Geo-Shape datatype »