[[geo-point]]
=== Geo-point datatype

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

* to find geo-points within a <<query-dsl-geo-bounding-box-query,bounding box>>,
  within a certain <<query-dsl-geo-distance-query,distance>> of a central point,
  within a <<query-dsl-geo-polygon-query,polygon>>, or within a
  <<query-dsl-geohash-cell-query,geohash>> cell.
* to aggregate documents by <<search-aggregations-bucket-geohashgrid-aggregation,geographically>>
  or by <<search-aggregations-bucket-geodistance-aggregation,distance>> from a central point.
* to integrate distance into a document's <<query-dsl-function-score-query,relevance score>>.
* to <<geo-sorting,sort>> documents by distance.

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

[source,js]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "my_type": {
      "properties": {
        "location": {
          "type": "geo_point"
        }
      }
    }
  }
}

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

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

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

PUT my_index/my_type/4
{
  "text": "Geo-point as an array",
  "location": [ -71.34, 41.12 ] <4>
}

GET my_index/_search
{
  "query": {
    "geo_bounding_box": { <5>
      "location": {
        "top_left": {
          "lat": 42,
          "lon": -72
        },
        "bottom_right": {
          "lat": 40,
          "lon": -74
        }
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
<1> Geo-point expressed as an object, with `lat` and `lon` keys.
<2> Geo-point expressed as a string with the format: `"lat,lon"`.
<3> Geo-point expressed as a geohash.
<4> Geo-point expressed as an array with the format: [ `lon`, `lat`]
<5> A geo-bounding box query which finds all geo-points that fall inside the box.

[IMPORTANT]
.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.

==================================================


[[geo-point-params]]
==== Parameters for `geo_point` fields

The following parameters are accepted by `geo_point` fields:

[horizontal]

<<geohash,`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,`geohash_precision`>>::

    The maximum length of the geohash to use for the `geohash` and
    `geohash_prefix` options.

<<geohash-prefix,`geohash_prefix`>>::

    Should the geo-point also be indexed as a geohash plus all its prefixes?
    Defaults to `false`.

<<ignore-malformed,`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,`lat_lon`>>::

    Should the geo-point also be indexed as `.lat` and `.lon` sub-fields?
    Accepts `true` and `false` (default).

<<precision-step,`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

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:


[source,js]
--------------------------------------------------
geopoint = doc['location'].value;
lat      = geopoint.lat;
lon      = geopoint.lon;
--------------------------------------------------

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

[source,js]
--------------------------------------------------
lat      = doc['location'].lat;
lon      = doc['location'].lon;
--------------------------------------------------