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.

Example graph

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

graph spatial functions

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

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

point()

Details

Syntax

point(input)

Description

Returns a 2D or 3D point object, given two or respectively three coordinate values in the Cartesian coordinate system or WGS 84 geographic coordinate system.

Arguments

Name

Type

Description

input

MAP

Cartesian 2D: {
x :: FLOAT,
y :: FLOAT,
crs = "cartesian" :: STRING,
srid = 7203 :: INTEGER
}

Cartesian 3D: {
x :: FLOAT,
y :: FLOAT,
z :: FLOAT,
crs = "cartesian-3D" :: STRING,
srid = 9157 :: INTEGER
}

WGS 84 2D: {
longitude | x :: FLOAT
latitude | y :: FLOAT
crs = "WGS-84-2D" :: STRING
srid = 4326 :: INTEGER
}

WGS 84 3D: {
longitude | x :: FLOAT,
latitude | y :: FLOAT,
height | z :: FLOAT,
crs = "WGS-84-3D" :: STRING,
srid = 4979 :: INTEGER
}

Returns

POINT

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) for 2D points or 'WGS-84-3D' (srid:4979) for 3D points.

If the coordinates are specified using x and y, then either the crs or srid field is required if a geographic CRS is desired.

If the height/z key and value is not provided, a 2D POINT will be returned in either the WGS 84 or Cartesian CRS, depending on the coordinate system used.

The crs or srid fields are optional and default to the Cartesian CRS (which means srid:7203) for 2D points or the 3D Cartesian CRS (which means srid:9157) for 3D points.

Example 1. point() - WGS 84 2D
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.

Result
point

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

Rows: 1

Example 2. point() - WGS 84 2D
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.

Result
point

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

Rows: 1

Example 3. point() - WGS 84 2D
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.

Result
officePoint

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

Rows: 1

Example 4. point() - WGS 84 3D
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.

Result
point

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

Rows: 1

Example 5. point() - Cartesian 2D
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.

Result
point

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

Rows: 1

Example 6. point() - Cartesian 3D
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.

Result
point

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

Rows: 1

Example 7. point() - null
Query
RETURN point(null) AS p

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

Result
p

<null>

Rows: 1

point.distance()

Details

Syntax

point.distance(from, to)

Description

Returns a FLOAT representing the distance between any two points in the same CRS. If the points are in the WGS 84 CRS, the function returns the geodesic distance (i.e., the shortest path along the curved surface of the Earth). If the points are in a Cartesian CRS, the function returns the Euclidean distance (i.e., the shortest straight-line distance in a flat, planar space).

Arguments

Name

Type

Description

from

POINT

A start point.

to

POINT

An end point in the same CRS as the start point.

Returns

FLOAT

  • 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.

Considerations

point.distance(null, null) return null.

point.distance(null, to) return null.

point.distance(from, 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 8. 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.

Result
dist

1.5

Rows: 1

Example 9. 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.

Result
dist

1269.9148706779097

Rows: 1

Example 10. 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.

Result
travelDistance

27842.0

Rows: 1

Example 11. 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.

Result
d

null

Rows: 1

point.withinBBox()

Details

Syntax

point.withinBBox(point, lowerLeft, upperRight)

Description

Returns true if the provided point is within the bounding box defined by the two provided points.

Arguments

Name

Type

Description

point

POINT

A point to be confirmed in the bounding box.

lowerLeft

POINT

The lower left side point of the bounding box.

upperRight

POINT

The upper right side point of the bounding box.

Returns

BOOLEAN

Considerations

point.withinBBox(point, lowerLeft, upperRight) 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 12. 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.

Result
result

true

Rows: 1

Example 13. 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.

Result
count(t)

1

Rows: 1

Example 14. 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.

Result
result

true

Rows: 1

Example 15. 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.

Result
in

null

Rows: 1