These functions can be used when working with and analysing geospatial data.
Function | Description |
---|---|
geo::area() | Calculates the area of a geometry |
geo::bearing() | Calculates the bearing between two geolocation points |
geo::centroid() | Calculates the centroid of a geometry |
geo::distance() | Calculates the distance between two geolocation points |
geo::hash::decode() | Decodes a geohash into a geometry point |
geo::hash::encode() | Encodes a geometry point into a geohash |
geo::is::valid() | Determines if a geometry type is a geography type |
point
is composed of two floats that represent the longitude (east/west) and latitude (north/south) of a location.geometry
is a type of object defined in the GeoJSON spec, of which Polygon is the most common. They can be passed in to the geo functions as objects that contain a “type” (such as “Polygon”) and “coordinates” (an array of points).geo::area
The geo::area
function calculates the area of a geometry in square metres.
API DEFINITIONgeo::area(geometry) -> number
The following example shows this function, and its output, when used in a RETURN
statement for four approximate points found on a map for the US state of Wyoming which has an area of 253,340 km2 and a mostly rectangular shape. Note: the doubled square brackets are because the function takes an array of an array to allow for more complex types such as MultiPolygon.
RETURN geo::area({ type: "Polygon", coordinates: [[ [-111.0690, 45.0032], [-104.0838, 44.9893], [-104.0910, 40.9974], [-111.0672, 40.9862] ]] });
Response253317731850.3478f
If the argument is not a geometry type, then an EMPTY
value will be returned:
RETURN geo::area(12345); null
geo::bearing
The geo::bearing
function calculates the bearing between two geolocation points. Bearing begins at 0 degrees to indicate north, increasing clockwise into positive values and decreasing counterclockwise into negative values that converge at 180 degrees.
API DEFINITIONgeo::bearing(point, point) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
-- LET used here for readability LET $paris = (2.358058597411099, 48.861109346459536); LET $le_puy_en_velay = (3.883428431947686, 45.04383588468415); RETURN geo::bearing($paris, $le_puy_en_velay);
Response164.18154786094604
If either argument is not a geolocation point, then an EMPTY
value will be returned:
RETURN geo::bearing(12345, true); null
geo::centroid
The geo::centroid
function calculates the centroid between multiple geolocation points.
API DEFINITIONgeo::centroid(geometry) -> number
The following example shows this function, and its output, when used in a RETURN
statement. Note: the doubled square brackets are because the function takes an array of an array to allow for more complex types such as MultiPolygon.
RETURN geo::centroid({ type: "Polygon", coordinates: [[ [-0.03921743611083, 51.88106875736589], -- London [30.48112752349519, 50.68377089794912], -- Kyiv [23.66174524001544, 42.94500782833793], -- Sofia [ 1.92481534361859, 41.69698118125476] -- Barcelona ]] });
The return value is a mountainous region somewhere in Austria:
Response(13.483896437936192, 47.07117241195589)
If either argument is not a geometry type, then an EMPTY
value will be returned:
RETURN geo::centroid(12345); null
geo::distance
The geo::distance
function calculates the haversine distance, in metres, between two geolocation points.
API DEFINITIONgeo::distance(point, point) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
let $london = (-0.04592553673505285, 51.555282574465764); let $harare = (30.463880214538577, -17.865161568822085); RETURN geo::distance($london, $harare);
Response8268604.251890702f
If either argument is not a geolocation point, then an EMPTY
value will be returned:
RETURN geo::distance(12345, true); null
geo::hash::decode
The geo::hash::decode
function converts a geohash into a geolocation point.
API DEFINITIONgeo::hash::decode(point) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN geo::hash::decode("mpuxk4s24f51");
Response(51.50986494496465, -0.11809204705059528)
If the argument is not a geolocation point, then an EMPTY
value will be returned:
RETURN geo::hash::decode(12345); null
geo::hash::encode
The geo::hash::encode
function converts a geolocation point into a geohash.
API DEFINITIONgeo::hash::encode(point) -> string
The function accepts a second argument, which determines the accuracy and granularity of the geohash.
API DEFINITIONgeo::hash::encode(point, number) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN geo::hash::encode( (51.509865, -0.118092) ); "mpuxk4s24f51"
The following example shows this function with two arguments, and its output, when used in a select statement:
RETURN geo::hash::encode( (51.509865, -0.118092), 5 ); "mpuxk"
If the first argument is not a geolocation point, then an EMPTY
value will be returned:
RETURN geo::hash::encode(12345); null
geo::is::valid
The geo::is::valid
function determines if a geometry type is a geography type. Geography types are used to store geolocation data in a Geographic Coordinate System (GCS), whereas geometry types can store geolocation data in any coordinate system, including GCS, mathematical planes, board game layouts, etc…
A geography type add the following constraint: each Point
coordinates are in the range of -180° to 180° for longitude and -90° to 90° for latitude.
API DEFINITIONgeo::is::valid(geometry) -> bool
The following examples show this function, and its output, when used in a RETURN
statement:
A valid geography pointRETURN geo::is::valid( (51.509865, -0.118092) ); true
Out of range geometry pointRETURN geo::is::valid( (-181.0, -0.118092) ); false