Improve this page

Geospatial Datatype

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

• to find geo-points within a polygon, or a certain distance of a central point.
• to aggregate documents geographically or by distance from a central point.
• to sort documents by distance.

Available data types:

• Point
• Circle
• Convex Polygon
• Convex Hull

Point

Use _point.

UPDATE /bank/1
{
  "checkin": {
    "_point": {
      "_longitude": -80.31727,
      "_latitude": 25.67927
    }
  }
}

Circle

Use _circle.

UPDATE /bank/2
{
  "neighborhood": {
    "_circle": {
      "_longitude": -101.601563,
      "_latitude": 18.885498,
      "_radius": 1000
    }
  }
}

The example show circle with radius of 1000 meters.

Convex Polygon

Use _polygon.

UPDATE /bank/3
{
  "neighborhood": {
    "_polygon": {
      "_latitude": [
        41.502530,
        41.507152,
        41.506734,
        41.502121
      ],
      "_longitude": [
        -74.015237,
        -74.015061,
        -74.009160,
        -74.009489
      ]
    }
  }
}

Concave Polygons
Note you must provide convex polygons; at the moment, concave polygons are not supported.

Convex Hull

Use _chull to calculate the convex hull (chull) for the coordinates using the Graham Scan Algorithm:

UPDATE /bank/4
{
  "neighborhood": {
    "_chull": {
      "_longitude": [
        -109.034104,
        -102.026812,
        -102.026812,
        -109.034104
      ],
      "_latitude": [
        40.993201,
        40.993201,
        36.993722,
        36.993722
      ]
    }
  }
}

This is the set of coordinates generate for the convex hull for the above example:

Latitude	Longitude	Height
-0.166828	-0.783064	0.599148
-0.261113	-0.756863	0.599148
-0.246869	-0.715576	0.653457
-0.157728	-0.740349	0.653457
-0.166828	-0.783064	0.599148

Extended Well-Known Text

Use _ewkt to represent shapes using the Extended Well-Known Text (EWKT) format. The following shapes are allowed types:

• POINT - Finds documents with the given point
• CIRCLE - Finds documents inside or with the given circle.
• CONVEX - Finds documents inside or with the given convex.
• POLYGON - Finds documents inside or with the given polygon.
• CHULL - Finds documents inside or with the given convex hull.
• MULTIPOINT - Finds documents inside the given vector of points.
• MULTIPCIRCLE - Finds documents inside the given vector of circles.
• MULTICONVEX - Finds documents inside the given vector of convexs.
• MULTIPOLYGON - Finds documents inside the given vector of polygons.
• MULTICHULL - Finds documents inside the given vector of convexs hull.

The following example indexes a point with latitude of 41.50343 and longitude of -74.01042.

UPDATE /bank/5
{
  "checkin": {
    "_ewkt": "POINT(-74.01042 41.50343)"
  }
}

Caution
Notice that for points in EWKT expressions, the correct coordinate order is POINT(longitude latitude), “longitude” first.

Accepted Coordinates

Additionally to the object formats exemplified above, coordinates also accept array formats and some text formats.

Here are examples of formats that work:

• Text with degrees, minutes, and seconds (DMS): 41°30'12.348"N 74°0'37.512"W
• Text with degrees and decimal minutes (DMM): 41 30.2058, -74 0.6252
• Text with decimal degrees (DD): 41.50343, -74.01042
• Extended Well-Known Text (EWKT): POINT(-74.01042 41.50343)
• Array of longitude and latitude pairs: [ -74.01042, 41.50343 ]

Here are some tips for formatting your coordinates so they work:

• Use the degree symbol instead of “d”.
• Use double quoted symbol (") instead of two single quoted symbols (and escape, in JSON strings).
• Use periods as decimals, not commas.
  • Incorrect: 41,50343, -74,01042.
  • Correct: 41.50343, -74.01042.
• List your latitude coordinates before longitude coordinates.
• Check that the first number in your latitude coordinate is between -90 and 90.
• Check that the first number in your longitude coordinate is between -180 and 180.

Unimplemented Feature!
DMS, DMM and DD text formats haven’t yet been implemented…
Pull requests are welcome!

For example, the following example indexes a point using an array of [ longitude, latitude ]:

UPDATE /bank/6
{
  "checkin": [ -74.01042, 41.50343 ]
}

Caution
Notice that for points in array mode, the correct coordinate order is [ longitude, latitude], “longitude” first.

Distance Units

Whenever distances need to be specified, e.g. for a radius or altitude, the distance unit can be specified as a double number representing distance in meters or as a string of the form number and distance unit e.g. “2.72km”

Supported Units

A number of distance units are supported, from millimeters to nautical miles

Metric

• mm (Millimeters)
• cm (Centimeters)
• m (Meters)
• km (Kilometers)

Imperial

• in (Inches)
• ft (Feet)
• yd (Yards)
• mi (Miles)
• nmi or NM (Nautical Miles)

Accuracy

Xapiand handles numerical ranges by trie indexing numerical values in a special string-encoded format with variable precision.

All numerical (and also dates, times and geospatial) values are converted to lexicographic sortable string representations and indexed with different precisions. A range of values is divided recursively into multiple intervals for searching: The center of the range is searched only with the lowest possible precision in the trie, while the boundaries are matched more exactly.

Default accuracy in geospatial fields is:

[ 3, 5, 8, 10, 12, 15 ]

This means the precisions for geospatial values will be calculated for each of those HTM levels.

See Hierarchical Triangular Mesh to find how HTM levels work.

Back

Next