You're viewing version 2.3 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Geoshape field type

A geoshape field type contains a geographic shape, such as a polygon or a collection of geographic points. To index a geoshape, OpenSearch tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. This provides a 10^-7decimal degree of precision, which represents near-perfect spatial resolution. Performance of this process is mostly impacted by the number of vertices in a polygon you are indexing.

Example

Create a mapping with a geoshape field type:

PUT testindex
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape"
      }
    }
  }
}

Formats

Geoshapes can be indexed in the following formats:

• GeoJSON
• Well-Known Text (WKT)

In both GeoJSON and WKT, the coordinates must be specified in the longitude, latitude order within coordinate arrays. Note that the longitude comes first in this format.

Geoshape types

The following table describes the possible geoshape types and their relationship to the GeoJSON and WKT types.

Point

A point is a single pair of coordinates specified by latitude and longitude.

Index a point in GeoJSON format:

PUT testindex/_doc/1
{
  "location" : {
    "type" : "point",
    "coordinates" : [74.0060, 40.7128]
  }
}

Index a point in WKT format:

PUT testindex/_doc/1
{
  "location" : "POINT (74.0060 40.7128)"
}

Line string

A line string is a line specified by two or more points. If the points are collinear, the line string is a straight line. Otherwise, the line string represents a path made of line segments.

Index a line string in GeoJSON format:

PUT testindex/_doc/2
{
  "location" : {
    "type" : "linestring",
    "coordinates" : [[74.0060, 40.7128], [71.0589, 42.3601]]
  }
}

Index a line string in WKT format:

PUT testindex/_doc/2
{
  "location" : "LINESTRING (74.0060 40.7128, 71.0589 42.3601)"
}

Polygon

A polygon is specified by a list of vertices in coordinate form. The polygon must be closed, meaning the last point must be the same as the first point. In the following example, a triangle is created using four points.

GeoJSON requires that you list the vertices of the polygon counterclockwise. WKT does not impose a specific order on vertices.

Index a polygon (triangle) in GeoJSON format:

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ]
    ]
  }
}

Index a polygon (triangle) in WKT format:

PUT testindex/_doc/3
{
  "location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128))"
}

The polygon may have holes inside. In this case, the coordinates field will contain multiple arrays. The first array represents the outer polygon, and each subsequent array represents a hole. Holes are represented as polygons and specified as arrays of coordinates.

GeoJSON requires that you list the vertices of the polygon counterclockwise and the vertices of the hole clockwise. WKT does not impose a specific order on vertices.

Index a polygon (triangle) with a triangular hole in GeoJSON format:

PUT testindex/_doc/4
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ],
      [
        [72.6734,41.7658], 
        [73.0515, 41.5582], 
        [72.6506, 41.5623],
        [72.6734, 41.7658]
      ]
    ]
  }
}

Index a polygon (triangle) with a triangular hole in WKT format:

PUT testindex/_doc/4
{
  "location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658))"
}

You can specify a polygon in OpenSearch by listing its vertices in clockwise or counterclockwise order. This works well for polygons that do not cross the date line (that are narrower than 180°). However, a polygon that crosses the date line (is wider than 180°) might be ambiguous because WKT does not impose a specific order on vertices. Thus, you must specify polygons that cross the date line by listing their vertices in counterclockwise order.

You can define an orientation parameter to specify the vertex traversal order at mapping time:

PUT testindex
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape",
        "orientation" : "left"
      }
    }
  }
}

Subsequently indexed documents can override the orientation setting:

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "orientation" : "cw",
    "coordinates" : [
      [[74.0060, 40.7128], 
      [71.0589, 42.3601], 
      [73.7562, 42.6526], 
      [74.0060, 40.7128]]
    ]
  }
}

Multi point

A multi point is an array of discrete related points that are not connected.

Index a multi point in GeoJSON format:

PUT testindex/_doc/6
{
  "location" : {
    "type" : "multipoint",
    "coordinates" : [
      [74.0060, 40.7128], 
      [71.0589, 42.3601]
    ]
  }
}

Index a multi point in WKT format:

PUT testindex/_doc/6
{
  "location" : "MULTIPOINT (74.0060 40.7128, 71.0589 42.3601)"
}

Multiline string

A multiline string is an array of line strings.

Index a line string in GeoJSON format:

PUT testindex/_doc/2
{
  "location" : {
    "type" : "multilinestring",
    "coordinates" : [
      [[74.0060, 40.7128], [71.0589, 42.3601]],
      [[73.7562, 42.6526], [72.6734, 41.7658]]
      ]
  }
}

Index a line string in WKT format:

PUT testindex/_doc/2
{
  "location" : "MULTILINESTRING ((74.0060 40.7128, 71.0589 42.3601), (73.7562 42.6526, 72.6734 41.7658))"
}

Multi polygon

A multi polygon is an array of polygons. In this example, the first polygon contains a hole, and the second does not.

Index a multi polygon in GeoJSON format:

PUT testindex/_doc/4
{
  "location" : {
    "type" : "multipolygon",
    "coordinates" : [
    [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ],
      [
        [73.0515, 41.5582], 
        [72.6506, 41.5623], 
        [72.6734, 41.7658], 
        [73.0515, 41.5582]
      ]
    ],
    [
      [
        [73.9146, 40.8252], 
        [73.8871, 41.0389], 
        [73.6853, 40.9747], 
        [73.9146, 40.8252]
      ]
    ]
  ]
  }
}

Index a multi polygon in WKT format:

PUT testindex/_doc/4
{
  "location" : "MULTIPOLYGON (((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658)), ((73.9146 40.8252, 73.6853 40.9747, 73.8871 41.0389, 73.9146 40.8252)))"
}

Geometry collection

A geometry collection is a collection of geoshapes that may be of different types.

Index a geometry collection in GeoJSON format:

PUT testindex/_doc/7
{
  "location" : {
    "type": "geometrycollection",
    "geometries": [
      {
        "type": "point",
        "coordinates": [74.0060, 40.7128]
      },
      {
        "type": "linestring",
        "coordinates": [[73.7562, 42.6526], [72.6734, 41.7658]]
      }
    ]
  }
}

Index a geometry collection in WKT format:

PUT testindex/_doc/7
{
  "location" : "GEOMETRYCOLLECTION (POINT (74.0060 40.7128), LINESTRING(73.7562 42.6526, 72.6734 41.7658))"
}

Envelope

An envelope is a bounding rectangle specified by top-left and bottom-right vertices. The GeoJSON format is [[minLon, maxLat], [maxLon, minLat]].

Index an envelope in GeoJSON format:

PUT testindex/_doc/2
{
  "location" : {
    "type" : "envelope",
    "coordinates" : [[71.0589, 42.3601], [74.0060, 40.7128]]
  }
}

In WKT format, use BBOX (minLon, maxLon, maxLat, minLat).

Index an envelope in WKT BBOX format:

PUT testindex/_doc/8
{
  "location" : "BBOX (71.0589, 74.0060, 42.3601, 40.7128)"
}

Parameters

The following table lists the parameters accepted by geoshape field types. All parameters are optional.