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) |
|
|
|
Point (WGS-84) |
|
|
|
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.
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.
records, summary, keys = 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 = pointThe 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.
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 = shardThe 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.
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 = pointDistance
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.
# 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.727922061357855Check your understanding
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.