Geoshape field typeedit

The geo_shape data type facilitates the indexing of and searching with arbitrary geo shapes such as rectangles and polygons. It should be used when either the data being indexed or the queries being executed contain shapes other than just points.

You can query documents using this type using a geo_shape query.

Mapping Optionsedit

The geo_shape mapping maps GeoJSON geometry objects to the geo_shape type. To enable it, users must explicitly map fields to the geo_shape type.

Option Description Default

orientation

Optional. Default orientation for the field’s polygons.

This parameter sets and returns only a RIGHT (counterclockwise) or LEFT (clockwise) value. However, you can specify either value in multiple ways.

To set RIGHT, use one of the following arguments or its uppercase variant:

  • right
  • counterclockwise
  • ccw

To set LEFT, use one of the following arguments or its uppercase variant:

  • left
  • clockwise
  • cw

RIGHT

ignore_malformed

If true, malformed GeoJSON or WKT shapes are ignored. If false (default), malformed GeoJSON and WKT shapes throw an exception and reject the entire document.

false

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, geopoints containing any more than latitude and longitude (two dimensions) values throw an exception and reject the whole document.

true

coerce

If true unclosed linear rings in polygons will be automatically closed.

false

Indexing approachedit

GeoShape types are indexed by decomposing the shape into a triangular mesh and indexing each triangle as a 7 dimension point in a BKD tree. This provides near perfect spatial resolution (down to 1e-7 decimal degree precision) since all spatial relations are computed using an encoded vector representation of the original shape. Performance of the tessellator primarily depends on the number of vertices that define the polygon/multi-polygon.

Exampleedit
PUT /example
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape"
      }
    }
  }
}

Input Structureedit

Shapes can be represented using either the GeoJSON or Well-Known Text (WKT) format. The following table provides a mapping of GeoJSON and WKT to Elasticsearch types:

GeoJSON Type WKT Type Elasticsearch Type Description

Point

POINT

point

A single geographic coordinate. Note: Elasticsearch uses WGS-84 coordinates only.

LineString

LINESTRING

linestring

An arbitrary line given two or more points.

Polygon

POLYGON

polygon

A closed polygon whose first and last point must match, thus requiring n + 1 vertices to create an n-sided polygon and a minimum of 4 vertices.

MultiPoint

MULTIPOINT

multipoint

An array of unconnected, but likely related points.

MultiLineString

MULTILINESTRING

multilinestring

An array of separate linestrings.

MultiPolygon

MULTIPOLYGON

multipolygon

An array of separate polygons.

GeometryCollection

GEOMETRYCOLLECTION

geometrycollection

A GeoJSON shape similar to the multi* shapes except that multiple types can coexist (e.g., a Point and a LineString).

N/A

BBOX

envelope

A bounding rectangle, or envelope, specified by specifying only the top left and bottom right points.

For all types, both the inner type and coordinates fields are required.

In GeoJSON and WKT, and therefore Elasticsearch, the correct coordinate order is longitude, latitude (X, Y) within coordinate arrays. This differs from many Geospatial APIs (e.g., Google Maps) that generally use the colloquial latitude, longitude (Y, X).

Pointedit

A point is a single geographic coordinate, such as the location of a building or the current position given by a smartphone’s Geolocation API. The following is an example of a point in GeoJSON.

POST /example/_doc
{
  "location" : {
    "type" : "point",
    "coordinates" : [-77.03653, 38.897676]
  }
}

The following is an example of a point in WKT:

POST /example/_doc
{
  "location" : "POINT (-77.03653 38.897676)"
}
LineStringedit

A linestring defined by an array of two or more positions. By specifying only two points, the linestring will represent a straight line. Specifying more than two points creates an arbitrary path. The following is an example of a LineString in GeoJSON.

POST /example/_doc
{
  "location" : {
    "type" : "linestring",
    "coordinates" : [[-77.03653, 38.897676], [-77.009051, 38.889939]]
  }
}

The following is an example of a LineString in WKT:

POST /example/_doc
{
  "location" : "LINESTRING (-77.03653 38.897676, -77.009051 38.889939)"
}

The above linestring would draw a straight line starting at the White House to the US Capitol Building.

Polygonedit

A polygon is defined by a list of a list of points. The first and last points in each (outer) list must be the same (the polygon must be closed). The following is an example of a Polygon in GeoJSON.

POST /example/_doc
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
    ]
  }
}

The following is an example of a Polygon in WKT:

POST /example/_doc
{
  "location" : "POLYGON ((100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0, 100.0 0.0))"
}

The first array represents the outer boundary of the polygon, the other arrays represent the interior shapes ("holes"). The following is a GeoJSON example of a polygon with a hole:

POST /example/_doc
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],
      [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
    ]
  }
}

The following is an example of a Polygon with a hole in WKT:

POST /example/_doc
{
  "location" : "POLYGON ((100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0, 100.0 0.0), (100.2 0.2, 100.8 0.2, 100.8 0.8, 100.2 0.8, 100.2 0.2))"
}
Polygon orientationedit

A polygon’s orientation indicates the order of its vertices: RIGHT (counterclockwise) or LEFT (clockwise).

You can set a default orientation for a geo_shape field using the orientation mapping parameter. You can override this default for specific polygons using the document-level orientation parameter.

For example, the following indexing request specifies a document-level orientation of LEFT.

POST /example/_doc
{
  "location" : {
    "type" : "polygon",
    "orientation" : "LEFT",
    "coordinates" : [
      [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ]
    ]
  }
}

Elasticsearch only uses a polygon’s orientation to determine if it crosses the international dateline (+/-180° longitude). If the difference between a polygon’s minimum longitude and the maximum longitude is less than 180°, the polygon doesn’t cross the dateline and its orientation has no effect.

If the difference between a polygon’s minimum longitude and the maximum longitude is 180° or greater, Elasticsearch checks whether the polygon’s document-level orientation differs from the default in the orientation mapping parameter. If the orientation differs, Elasticsearch considers the polygon to cross the international dateline and splits the polygon at the dateline.

MultiPointedit

The following is an example of a list of GeoJSON points:

POST /example/_doc
{
  "location" : {
    "type" : "multipoint",
    "coordinates" : [
      [102.0, 2.0], [103.0, 2.0]
    ]
  }
}

The following is an example of a list of WKT points:

POST /example/_doc
{
  "location" : "MULTIPOINT (102.0 2.0, 103.0 2.0)"
}
MultiLineStringedit

The following is an example of a list of GeoJSON linestrings:

POST /example/_doc
{
  "location" : {
    "type" : "multilinestring",
    "coordinates" : [
      [ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0] ],
      [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0] ],
      [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8] ]
    ]
  }
}

The following is an example of a list of WKT linestrings:

POST /example/_doc
{
  "location" : "MULTILINESTRING ((102.0 2.0, 103.0 2.0, 103.0 3.0, 102.0 3.0), (100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0), (100.2 0.2, 100.8 0.2, 100.8 0.8, 100.2 0.8))"
}
MultiPolygonedit

The following is an example of a list of GeoJSON polygons (second polygon contains a hole):

POST /example/_doc
{
  "location" : {
    "type" : "multipolygon",
    "coordinates" : [
      [ [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]] ],
      [ [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]],
        [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]] ]
    ]
  }
}

The following is an example of a list of WKT polygons (second polygon contains a hole):

POST /example/_doc
{
  "location" : "MULTIPOLYGON (((102.0 2.0, 103.0 2.0, 103.0 3.0, 102.0 3.0, 102.0 2.0)), ((100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0, 100.0 0.0), (100.2 0.2, 100.8 0.2, 100.8 0.8, 100.2 0.8, 100.2 0.2)))"
}
Geometry Collectionedit

The following is an example of a collection of GeoJSON geometry objects:

POST /example/_doc
{
  "location" : {
    "type": "geometrycollection",
    "geometries": [
      {
        "type": "point",
        "coordinates": [100.0, 0.0]
      },
      {
        "type": "linestring",
        "coordinates": [ [101.0, 0.0], [102.0, 1.0] ]
      }
    ]
  }
}

The following is an example of a collection of WKT geometry objects:

POST /example/_doc
{
  "location" : "GEOMETRYCOLLECTION (POINT (100.0 0.0), LINESTRING (101.0 0.0, 102.0 1.0))"
}
Envelopeedit

Elasticsearch supports an envelope type, which consists of coordinates for upper left and lower right points of the shape to represent a bounding rectangle in the format [[minLon, maxLat], [maxLon, minLat]]:

POST /example/_doc
{
  "location" : {
    "type" : "envelope",
    "coordinates" : [ [100.0, 1.0], [101.0, 0.0] ]
  }
}

The following is an example of an envelope using the WKT BBOX format:

NOTE: WKT specification expects the following order: minLon, maxLon, maxLat, minLat.

POST /example/_doc
{
  "location" : "BBOX (100.0, 102.0, 2.0, 0.0)"
}
Circleedit

Neither GeoJSON nor WKT supports a point-radius circle type. Instead, use a circle ingest processor to approximate the circle as a polygon.

Sorting and Retrieving index Shapesedit

Due to the complex input structure and index representation of shapes, it is not currently possible to sort shapes or retrieve their fields directly. The geo_shape value is only retrievable through the _source field.