Spatial functions

Functions:

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

Graph
  N0 [
    label = "{TrainStation|longitude = 12.56459\lcity = \'Copenhagen\'\llatitude = 55.672874\l}"
  ]
  N0 -> N1 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "TRAVEL_ROUTE\n"
  ]
  N1 [
    label = "{Office|longitude = 12.994341\lcity = \'Malmo\'\llatitude = 55.611784\l}"
  ]

distance()

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

  • If the points 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 points 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 points 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.

Syntax: distance(point1, point2)

Returns:

A 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:

distance(null, null), distance(null, point2) and distance(point1, null) all return null.

Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return null.
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 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
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 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
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(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
Query
RETURN 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() - 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.

Syntax: 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 number 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.
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 5. Result
point

point({x: 56.7, y: 12.78, crs: 'wgs-84'})

Rows: 1
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 6. Result
point

point({x: 2.3, y: 4.5, crs: 'wgs-84'})

Rows: 1
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 7. Result
officePoint

point({x: 12.994341, y: 55.611784, crs: 'wgs-84'})

Rows: 1
Query
RETURN point(null) AS p

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

Table 8. 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.

Syntax: 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 number 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.
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 9. Result
point

point({x: 56.7, y: 12.78, z: 8.0, crs: 'wgs-84-3d'})

Rows: 1

point() - Cartesian 2D

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

Syntax: 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 number 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).
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 10. Result
point

point({x: 2.3, y: 4.5, crs: 'cartesian'})

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.

Syntax: 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 number 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).
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 11. Result
point

point({x: 2.3, y: 4.5, z: 2.0, crs: 'cartesian-3d'})

Rows: 1