Spatial functions

Spatial functions are used to specify 2D or 3D `POINT` values in a Coordinate Reference System (CRS) and to calculate the geodesic distance between two `POINT` values.

The following graph is used for some of the examples below.

To recreate the graph, run the following query in an empty Neo4j database:

``````CREATE
(copenhagen:TrainStation {longitude: 12.564590, latitude: 55.672874, city: 'Copenhagen'}),
(malmo:Office {longitude: 12.994341, latitude: 55.611784, city: 'Malmo'}),
(copenhagen)-[:TRAVEL_ROUTE]->(malmo)``````

point.distance()

`point.distance()` returns a `FLOAT` representing the geodesic distance between two points in the same Coordinate Reference System (CRS).

• If the `POINT` values are in the Cartesian CRS (2D or 3D), then the units of the returned distance will be the same as the units of the points, calculated using Pythagoras' theorem.

• If the `POINT` values are in the WGS-84 CRS (2D), then the units of the returned distance will be meters, based on the haversine formula over a spherical earth approximation.

• If the `POINT` values are in the WGS-84 CRS (3D), then the units of the returned distance will be meters.

• The distance is calculated in two steps.

• First, a haversine formula over a spherical earth is used, at the average height of the two points.

• To account for the difference in height, Pythagoras' theorem is used, combining the previously calculated spherical distance with the height difference.

• This formula works well for points close to the earth’s surface; for instance, it is well-suited for calculating the distance of an airplane flight. It is less suitable for greater heights, however, such as when calculating the distance between two satellites.

``point.distance(point1, point2)``

Returns:

 `FLOAT`

Arguments:

Name Description

`point1`

A `POINT` in either a geographic or cartesian coordinate system.

`point2`

A `POINT` in the same CRS as `point1`.

Considerations:

 `point.distance(null, null)` return `null`. `point.distance(null, point2)` return `null`. `point.distance(point1, null)` return `null`. Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`.
Example 1. point.distance()
Query
``````WITH
point({x: 2.3, y: 4.5, crs: 'cartesian'}) AS p1,
point({x: 1.1, y: 5.4, crs: 'cartesian'}) AS p2
RETURN point.distance(p1,p2) AS dist``````

The distance between two 2D points in the Cartesian CRS is returned.

Table 1. Result
dist

`1.5`

Rows: 1

Example 2. point.distance()
Query
``````WITH
point({longitude: 12.78, latitude: 56.7, height: 100}) AS p1,
point({latitude: 56.71, longitude: 12.79, height: 100}) AS p2
RETURN point.distance(p1, p2) AS dist``````

The distance between two 3D points in the WGS 84 CRS is returned.

Table 2. Result
dist

`1269.9148706779097`

Rows: 1

Example 3. point.distance()
Query
``````MATCH (t:TrainStation)-[:TRAVEL_ROUTE]->(o:Office)
WITH
point({longitude: t.longitude, latitude: t.latitude}) AS trainPoint,
point({longitude: o.longitude, latitude: o.latitude}) AS officePoint
RETURN round(point.distance(trainPoint, officePoint)) AS travelDistance``````

The distance between the train station in Copenhagen and the Neo4j office in Malmo is returned.

Table 3. Result
travelDistance

`27842.0`

Rows: 1

Example 4. point.distance()
Query
``RETURN point.distance(null, point({longitude: 56.7, latitude: 12.78})) AS d``

If `null` is provided as one or both of the arguments, `null` is returned.

Table 4. Result
d

`<null>`

Rows: 1

point.withinBBox()

`point.withinBBox()` takes the following arguments:

• The `POINT` to check.

• The lower-left (south-west) `POINT` of a bounding box.

• The upper-right (or north-east) `POINT` of a bounding box.

The return value will be true if the provided point is contained in the bounding box (boundary included), otherwise the return value will be false.

``point.withinBBox(point, lowerLeft, upperRight)``

Returns:

 `BOOLEAN`

Arguments:

Name Description

`point`

A `POINT` in either a geographic or cartesian coordinate system.

`lowerLeft`

A `POINT` in the same CRS as 'point'.

`upperRight`

A `POINT` in the same CRS as 'point'.

Considerations:

 `point.withinBBox(p1, p2, p3)` will return `null` if any of the arguments evaluate to `null`. Attempting to use `POINT` values with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`. `point.withinBBox` will handle crossing the 180th meridian in geographic coordinates. Switching the longitude of the `lowerLeft` and `upperRight` in geographic coordinates will switch the direction of the resulting bounding box. Switching the latitude of the `lowerLeft` and `upperRight` in geographic coordinates so that the former is north of the latter will result in an empty range.
Example 5. point.withinBBox()
Query
``````WITH
point({x: 0, y: 0, crs: 'cartesian'}) AS lowerLeft,
point({x: 10, y: 10, crs: 'cartesian'}) AS upperRight
RETURN point.withinBBox(point({x: 5, y: 5, crs: 'cartesian'}), lowerLeft, upperRight) AS result``````

Checking if a point in Cartesian CRS is contained in the bounding box.

Table 5. Result
result

`true`

Rows: 1

Example 6. point.withinBBox()
Query
``````WITH
point({longitude: 12.53, latitude: 55.66}) AS lowerLeft,
point({longitude: 12.614, latitude: 55.70}) AS upperRight
MATCH (t:TrainStation)
WHERE point.withinBBox(point({longitude: t.longitude, latitude: t.latitude}), lowerLeft, upperRight)
RETURN count(t)``````

Finds all train stations contained in a bounding box around Copenhagen.

Table 6. Result
count(t)

`1`

Rows: 1

Example 7. point.withinBBox()
Query
``````WITH
point({longitude: 179, latitude: 55.66}) AS lowerLeft,
point({longitude: -179, latitude: 55.70}) AS upperRight
RETURN point.withinBBox(point({longitude: 180, latitude: 55.66}), lowerLeft, upperRight) AS result``````

A bounding box that crosses the 180th meridian.

Table 7. Result
result

`true`

Rows: 1

Example 8. point.withinBBox()
Query
``````RETURN
point.withinBBox(
null,
point({longitude: 56.7, latitude: 12.78}),
point({longitude: 57.0, latitude: 13.0})
) AS in``````

If `null` is provided as any of the arguments, `null` is returned.

Table 8. Result
in

`<null>`

Rows: 1

point() - WGS 84 2D

`point({longitude | x, latitude | y [, crs][, srid]})` returns a 2D `POINT` in the WGS 84 CRS corresponding to the given coordinate values.

``point({longitude | x, latitude | y [, crs][, srid]})``

Returns:

 A 2D `POINT` in WGS 84.

Arguments:

Name Description

`A single map consisting of the following:`

`longitude/x`

A numeric expression that represents the longitude/x value in decimal degrees.

`latitude/y`

A numeric expression that represents the latitude/y value in decimal degrees.

`crs`

The optional `STRING` `'WGS-84'`.

`srid`

The optional `INTEGER` `4326`.

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84'` (`srid:4326`). If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired.
Example 9. point()
Query
``RETURN point({longitude: 56.7, latitude: 12.78}) AS point``

A 2D `POINT` with a `longitude` of `56.7` and a `latitude` of `12.78` in the WGS 84 CRS is returned.

Table 9. Result
point

`point({srid:4326, x:56.7, y:12.78})`

Rows: 1

Example 10. point()
Query
``RETURN point({x: 2.3, y: 4.5, crs: 'WGS-84'}) AS point``

`x` and `y` coordinates may be used in the WGS 84 CRS instead of `longitude` and `latitude`, respectively, providing `crs` is set to `'WGS-84'`, or `srid` is set to `4326`.

Table 10. Result
point

`point({srid:4326, x:2.3, y:4.5})`

Rows: 1

Example 11. point()
Query
``````MATCH (p:Office)
RETURN point({longitude: p.longitude, latitude: p.latitude}) AS officePoint``````

A 2D `POINT` representing the coordinates of the city of Malmo in the WGS 84 CRS is returned.

Table 11. Result
officePoint

`point({srid:4326, x:12.994341, y:55.611784})`

Rows: 1

Example 12. point()
Query
``RETURN point(null) AS p``

If `null` is provided as the argument, `null` is returned.

Table 12. Result
p

`<null>`

Rows: 1

point() - WGS 84 3D

`point({longitude | x, latitude | y, height | z, [, crs][, srid]})` returns a 3D `POINT` in the WGS 84 CRS corresponding to the given coordinate values.

``point({longitude | x, latitude | y, height | z, [, crs][, srid]})``

Returns:

 A 3D `POINT` in WGS 84.

Arguments:

Name Description

`A single map consisting of the following:`

`longitude/x`

A numeric expression that represents the longitude/x value in decimal degrees.

`latitude/y`

A numeric expression that represents the latitude/y value in decimal degrees.

`height/z`

A numeric expression that represents the height/z value in meters.

`crs`

The optional `STRING` `'WGS-84-3D'`.

`srid`

The optional `INTEGER` `4979`.

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. If the `height/z` key and value is not provided, a 2D `POINT` in the WGS 84 CRS will be returned. If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84-3D'` (`srid:4979`). If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired.
Example 13. point()
Query
``RETURN point({longitude: 56.7, latitude: 12.78, height: 8}) AS point``

A 3D `POINT` with a `longitude` of `56.7`, a `latitude` of `12.78` and a height of `8` meters in the WGS 84 CRS is returned.

Table 13. Result
point

`point({srid:4979, x:56.7, y:12.78, z:8.0})`

Rows: 1

point() - Cartesian 2D

`point({x, y [, crs][, srid]})` returns a 2D `POINT` in the Cartesian CRS corresponding to the given coordinate values.

``point({x, y [, crs][, srid]})``

Returns:

 A 2D `POINT` in Cartesian.

Arguments:

Name Description

`A single map consisting of the following:`

`x`

A numeric expression.

`y`

A numeric expression.

`crs`

The optional `STRING` `'cartesian'`.

`srid`

The optional `INTEGER` `7203`.

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. The `crs` or `srid` fields are optional and default to the Cartesian CRS (which means `srid:7203`).
Example 14. point()
Query
``RETURN point({x: 2.3, y: 4.5}) AS point``

A 2D `POINT` with an `x` coordinate of `2.3` and a `y` coordinate of `4.5` in the Cartesian CRS is returned.

Table 14. Result
point

`point({srid:7203, x:2.3, y:4.5})`

Rows: 1

point() - Cartesian 3D

`point({x, y, z, [, crs][, srid]})` returns a 3D `POINT` in the Cartesian CRS corresponding to the given coordinate values.

``point({x, y, z, [, crs][, srid]})``

Returns:

 A 3D `POINT` in Cartesian.

Arguments:

Name Description

`A single map consisting of the following:`

`x`

A numeric expression.

`y`

A numeric expression.

`z`

A numeric expression.

`crs`

The optional `STRING` `'cartesian-3D'`.

`srid`

The optional `INTEGER` `9157`.

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. If the `z` key and value is not provided, a 2D `POINT` in the Cartesian CRS will be returned. The `crs` or `srid` fields are optional and default to the 3D Cartesian CRS (which means `srid:9157`).
Example 15. point()
Query
``RETURN point({x: 2.3, y: 4.5, z: 2}) AS point``

A 3D `POINT` with an `x` coordinate of `2.3`, a `y` coordinate of `4.5` and a `z` coordinate of `2` in the Cartesian CRS is returned.

Table 15. Result
point

`point({srid:9157, x:2.3, y:4.5, z:2.0})`

Rows: 1