Geospatial Datatype
Edit pageFields of type geospatial (also spelled geo) 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:
Use _point.
UPDATE /bank/1
{ "checkin": { "_point": { "_longitude": -80.31727, "_latitude": 25.67927 } }}Circle
Section titled “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
Section titled “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 ] } }}Convex Hull
Section titled “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 generated for the convex hull for the above example (points on the
unit sphere, as Cartesian x, y, z: each row’s squares add up to 1):
| x | y | z |
|---|---|---|
| -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
Section titled “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.
- MULTICIRCLE - 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.
- GEOMETRYCOLLECTION - A collection of shapes.
- GEOMETRYINTERSECTION - The intersection of shapes.
A SRID=<n>; prefix names the coordinate system.
The following example indexes a point with latitude of 41.50343 and
longitude of -74.01042 into a location field (the checkin field on the
sample data already holds a point, and a geo field can only carry one shape):
UPDATE /bank/5
{ "location": { "_ewkt": "POINT(-74.01042 41.50343)" }}Accepted Coordinates
Section titled “Accepted Coordinates”Additionally to the object formats exemplified above, coordinates also accept array formats and some text formats.
Here are the formats that work:
- Extended Well-Known Text (EWKT):
POINT(-74.01042 41.50343) - Array of longitude and latitude pairs:
[ -74.01042, 41.50343 ]
A text value is read as EWKT only: the DMS, DMM and DD text forms (41°30'12.348"N 74°0'37.512"W,
41 30.2058, -74 0.6252, 41.50343, -74.01042) are not implemented and answer 400.
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.
- Incorrect:
- List your longitude coordinates before latitude coordinates, in arrays and in EWKT.
- 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.
For example, the following example indexes a point using an array of
[ longitude, latitude ]:
UPDATE /bank/6
{ "checkin": [ -74.01042, 41.50343 ]}Distance Units
Section titled “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. “2km” or “272m” (the number is an integer: “2.72km” answers 400)
Supported Units
Section titled “Supported Units”A number of distance units are supported, from millimeters to nautical miles
Metric
Section titled “Metric”mm(Millimeters)cm(Centimeters)m(Meters)km(Kilometers)
Imperial
Section titled “Imperial”in(Inches)ft(Feet)yd(Yards)mi(Miles)nmiorNM(Nautical Miles)
Accuracy
Section titled “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.