GraphAcademy

Using Neo4j with Go

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

In Go, points are represented by the neo4j.Point2D and neo4j.Point3D types, which provide methods to access the coordinates and SRID of the point.

SRID

The Spatial Reference Identifier (SRID) is a unique identifier used to define the type of coordinate system used.

Cypher Type Go Type SRID 3D SRID

Point (Cartesian)

neo4j.Point2D / neo4j.Point3D

7203

9157

Point (WGS-84)

neo4j.Point2D / neo4j.Point3D

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 creating a neo4j.Point2D or neo4j.Point3D struct, or by passing x, y and optionally z values to the point function in Cypher.

go
import "github.com/neo4j/neo4j-go-driver/v5/neo4j"

// 2D Cartesian point
point2D := neo4j.Point2D{
    X: 1.23,
    Y: 4.56,
    SpatialRefId: 7203, // Cartesian SRID
}

// 3D Cartesian point
point3D := neo4j.Point3D{
    X: 1.23,
    Y: 4.56,
    Z: 7.89,
    SpatialRefId: 9157, // 3D Cartesian SRID
}

CartesianPoint

The driver will convert point data types created with x, y and z values to instances of the neo4j.Point2D or neo4j.Point3D types.

The values can be accessed using the X, Y, Z and SpatialRefId fields.

go
result, err := neo4j.ExecuteQuery(ctx, driver, `
RETURN point({x: 1.23, y: 4.56, z: 7.89}) AS threeD
`, nil, neo4j.EagerResultTransformer)

if err == nil && len(result.Records) > 0 {
    point, _ := result.Records[0].Get("threeD")
    if p3d, ok := point.(neo4j.Point3D); ok {
        fmt.Printf("X: %f, Y: %f, Z: %f, SRID: %d\n",
            p3d.X, p3d.Y, p3d.Z, p3d.SpatialRefId)
    }
}

WGS84Point

A WGS (World Geodetic System) point consists of longitude (X) and latitude (Y) values. An additional height (Z) value can be provided to define a three-dimensional point.

You can create a WGS84 point by creating a neo4j.Point2D or neo4j.Point3D struct with the appropriate SRID, or by passing longitude, latitude and height values to the point function in Cypher.

go
// London coordinates (2D)
london := neo4j.Point2D{
    X: -0.118092,  // longitude
    Y: 51.509865,  // latitude
    SpatialRefId: 4326, // WGS-84 SRID
}

// The Shard with height (3D)
shard := neo4j.Point3D{
    X: -0.086500,  // longitude
    Y: 51.504501,  // latitude
    Z: 310,        // height in meters
    SpatialRefId: 4979, // WGS-84 3D SRID
}

WGS84Point

The driver will return neo4j.Point2D or neo4j.Point3D objects when point data types are created with latitude and longitude values in Cypher.

go
result, err := neo4j.ExecuteQuery(ctx, driver, `
RETURN point({ latitude: 51.5, longitude: -0.118, height: 100 }) AS point
`, nil, neo4j.EagerResultTransformer)

if err == nil && len(result.Records) > 0 {
    point, _ := result.Records[0].Get("point")
    if p3d, ok := point.(neo4j.Point3D); ok {
        longitude := p3d.X
        latitude := p3d.Y
        height := p3d.Z
        srid := p3d.SpatialRefId
        fmt.Printf("Lon: %f, Lat: %f, Height: %f, SRID: %d\n",
            longitude, latitude, height, srid)
    }
}

Distance

The point.distance function can be used to calculate the distance between two points with the same SRID.

The result is a float64 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 an error.

go
// Create two Cartesian points
point1 := neo4j.Point2D{X: 1.23, Y: 4.56, SpatialRefId: 7203}
point2 := neo4j.Point2D{X: 2.34, Y: 5.67, SpatialRefId: 7203}

// Query the distance using Cypher
result, err := neo4j.ExecuteQuery(ctx, driver, `
RETURN point.distance($p1, $p2) AS distance
`, map[string]any{
    "p1": point1,
    "p2": point2,
}, neo4j.EagerResultTransformer)

if err == nil && len(result.Records) > 0 {
    distance, _ := result.Records[0].Get("distance")
    fmt.Printf("Distance: %f\n", distance.(float64))
}

Lesson Summary

In this lesson, you learned how to work with 2D and 3D Cartesian and WGS-84 points using the Go driver:

  • The neo4j.Point2D and neo4j.Point3D types represent spatial data in Go

  • You can create points directly in Go or through Cypher functions

  • Cartesian points use x, y coordinates with SRID 7203 (2D) or 9157 (3D)

  • WGS-84 points use longitude, latitude coordinates with SRID 4326 (2D) or 4979 (3D)

  • The point.distance function calculates distances between compatible points

  • Point coordinates can be accessed using the X, Y, Z and SpatialRefId fields

For more information on Spatial types, view the spatial types page in Cypher Manual or the related Go manual types and mapping page.

Chatbot

How can I help you today?