GraphAcademy

Using Neo4j with Python

The Driver

Handling results

Best practices

Spatial types

Points and locations

Neo4j has built-in support for two-dimensional and three-dimensional spatial data types. These are referred to as points. A point may represent geographic coordinates (longitude, latitude) or Cartesian coordinates (x, y).

Depending on the values used to create the point, it can either be a CartesianPoint or a WGS84Point. If you specify three values, these are considered three dimensional points. Otherwise, they are considered two dimensional points.

In Python, these values are represented by the neo4j.spatial.CartesianPoint and neo4j.spatial.WGS84Point classes, which are subclasses of the neo4j.spatial.Point class.

Cypher Type Python Type SRID 3D SRID

Point (Cartesian)

neo4j.spatial.CartesianPoint

7203

9157

Point (WGS-84)

neo4j.spatial.WGS84Point

4326

4979

CartesianPoint

A Cartesian Point defines a point with x and y coordinates. An additional z value can be provided to define a three-dimensional point.

You can create a cartesian point by passing a tuple of values to the CartesianPoint constructor or by passing x, y and z values to the point function in Cypher.

python
CartesianPoint
from neo4j.spatial import CartesianPoint

two_d = CartesianPoint((x, y))
three_d = CartesianPoint((x, y, z))

The driver will convert point data types created with an x, y and z value to an instance of the CartesianPoint class.

python
records, summary, keys = driver.execute_query = driver.execute_query("""
RETURN point({x: 1.23, y: 4.56, z: 7.89}) AS threeD
""")

point = records[0]["threeD"]

# <1> Accessing attributes
print(point.x, point.y, point.z, point.srid) # 1.23, 4.56, 7.89, 9157

# <2> Destructuring
x, y, z = point

The values can be accessed using the x, y and z attributes <1> or by destructuring the point <2>.

WGS84Point

A WSG (World Geodetic System) point consists of a latitude and longitude value. An additional height value can be provided to define a three-dimensional point and can be created by passing a tuple of values to the WGS84Point constructor or by passing longitude, latitude and height values to the point function in Cypher.

python
WGS84Point
from neo4j.spatial import WGS84Point

ldn = WGS84Point((-0.118092, 51.509865))
print(ldn.longitude, ldn.latitude, ldn.srid) # -0.118092, 51.509865, 4326

shard = WGS84Point((-0.086500, 51.504501, 310))
print(shard.longitude, shard.latitude, shard.height, shard.srid) # -0.0865, 51.504501, 310, 4979

# Using destructuring
longitude, latitude, height = shard

The driver will return WGS84Point objects when point data types are created with latitude and longitude values in Cypher. The values can be accessed using the longitude, latitude and height attributes or by destructuring the point.

python
Using point()
records, summary, keys = driver.execute_query("""
RETURN point({
    latitude: 51.5,
    longitude: -0.118,
    height: 100
}) AS point
""")

point = records[0]["point"]
longitude, latitude, height = point

Distance

The point.distance function can be used to calculate the distance between two points with the same SRID. The result is a float representing the distance in a straight line between the two points.

SRIDs must be compatible

If the SRID values are different, the function will return None.

python
# Create two points
point1 = CartesianPoint((1, 1))
point2 = CartesianPoint((10, 10))

# Query the distance using Cypher
records, summary, keys = driver.execute_query("""
RETURN point.distance($p1, $p2) AS distance
""", p1=point1, p2=point2)

# Print the distance from the result
distance = records[0]["distance"]
print(distance)  # 12.727922061357855

Advance to challenge

Lesson Summary

In this lesson, you learned about the CartesianPoint and WGS84Point classes and how to use them in Python.

Regardless of the type of point, you can always access the individual components by destructuring the point object.

For more information on Spatial types, view the Spatial types page in Cypher Manual.