A5

Go implementation of A5, a geospatial index that partitions the world into pentagonal cells.

Cells are available at 31 different resolution levels, with the largest cell covering the whole world, and the smallest less than 30mm². Within each resolution level the cells have equal area, as per the OGC definition.

For more information, see the A5 documentation.

Installation

go get github.com/a5geo/a5-go

Usage

package main

import (
	"fmt"

	a5 "github.com/a5geo/a5-go"
)

func main() {
	// Convert coordinates to a cell ID
	lonLat := a5.LonLat{-73.9857, 40.7484} // New York City
	cellID, _ := a5.LonLatToCell(lonLat, 10)
	fmt.Printf("Cell ID: %d\n", cellID)

	// Convert a cell ID back to coordinates
	center := a5.CellToLonLat(cellID)
	fmt.Printf("Center: %v\n", center)

	// Get the resolution of a cell
	res := a5.GetResolution(cellID)
	fmt.Printf("Resolution: %d\n", res)

	// Navigate the hierarchy
	parent, _ := a5.CellToParent(cellID, res-1)
	children, _ := a5.CellToChildren(cellID, res+1)
	fmt.Printf("Parent: %d, Children: %d\n", parent, len(children))

	// Compact and uncompact cell sets
	compacted := a5.Compact(children)
	fmt.Printf("Compacted: %v\n", compacted)
}

Why Pentagons?

A5 uses a pentagonal tiling of a dodecahedron. The dodecahedron has the lowest vertex curvature of all the Platonic solids, making it the most spherical. This minimizes cell distortion when projecting onto the globe — the lower the original vertex curvature, the less warping is introduced by the projection.

Unlike other DGGSs (H3 uses hexagons, S2 uses squares, HTM uses triangles), A5 has a single cell topology with no mixed cell shapes.

Key Features

• 31 resolution levels from whole-world to sub-centimeter precision
• Equal-area cells at each resolution level, preventing spatial bias
• 64-bit integer cell IDs with Hilbert curve ordering for spatial locality
• Single cell topology — only pentagons, no mixed shapes
• Zero dependencies — pure Go implementation

API

Indexing

• LonLatToCell(lonLat, resolution) — geographic coordinates to cell ID
• CellToLonLat(cellID) — cell ID to center coordinates

Hierarchy

• GetResolution(cellID) — get the resolution level of a cell
• CellToParent(cellID, parentRes) — get the parent cell at a lower resolution
• CellToChildren(cellID, childRes) — get child cells at a higher resolution

Compaction

• Compact(cells) — merge complete sibling groups into parent cells
• Uncompact(cells, targetRes) — expand cells to a target resolution

Serialization

• Serialize(cell) — encode an A5Cell to a uint64
• Deserialize(cellID) — decode a uint64 to an A5Cell

Related Projects

• a5 — TypeScript (reference implementation)
• a5-rs — Rust
• a5-py — Python

License

Apache 2.0