H3-Go

This library is a pure-Go implementation of the H3 Core Library. It needs no C toolchain and no cgo. For API reference, see the H3 Documentation.

This is v4 of this library, supporting H3 v4.

Check out v3 or checkout the git tag for the version you need.

Migrating from v3?

Check out v3 to v4 migration guide. There have been no breaking changes to the format of H3 indexes. Indexes generated by older versions can be parsed in v4, and vice-versa.

Usage

Installation

go get github.com/uber/h3-go/v4

Quickstart

import "github.com/uber/h3-go/v4"

func ExampleLatLngToCell() {
	latLng := h3.NewLatLng(37.775938728915946, -122.41795063018799)
	resolution := 9 // between 0 (biggest cell) and 15 (smallest cell)

	cell, err := h3.LatLngToCell(latLng, resolution)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(cell)
	// Output:
	// 8928308280fffff
}

C API

Notes

• LatLng returns Lat and Lng as degrees, instead of radians.
• H3 C API function prefixes of get have been dropped in support of Golang's Getter naming style.
• Convenience methods have been added to various types where that type was the main or only argument.

Bindings

C API	Go API
latLngToCell	LatLngToCell, LatLng#Cell
cellToLatLng	CellToLatLng, Cell#LatLng
cellToBoundary	CellToBoundary, Cell#Boundary
gridDisk	GridDisk, Cell#GridDisk
gridDisksUnsafe	GridDisksUnsafe
gridDiskDistances	GridDiskDistances, Cell#GridDiskDistances
gridDiskDistancesSafe	GridDiskDistancesSafe, Cell#GridDiskDistancesSafe
gridDiskDistancesUnsafe	GridDiskDistancesUnsafe, Cell#GridDiskDistancesUnsafe
gridRing	GridRing, Cell#GridRing
gridRingUnsafe	GridRingUnsafe, Cell#GridRingUnsafe
polygonToCells	PolygonToCells, GeoPolygon#Cells
cellsToMultiPolygon	CellsToMultiPolygon
degsToRads	DegsToRads
radsToDegs	RadsToDegs
greatCircleDistance	GreatCircleDistance* (3/3)
getHexagonAreaAvg	HexagonAreaAvg* (3/3)
cellArea	CellArea* (3/3)
getHexagonEdgeLengthAvg	HexagonEdgeLengthAvg* (2/2)
exactEdgeLength	EdgeLength* (3/3)
getNumCells	NumCells
getRes0Cells	Res0Cells
getPentagons	Pentagons
getResolution	Resolution
getBaseCellNumber	BaseCellNumber, Cell#BaseCellNumber
stringToH3	IndexFromString, Cell#UnmarshalText
h3ToString	IndexToString, Cell#String, Cell#MarshalText
isValidCell	Cell#IsValid
cellToParent	Cell#Parent, Cell#ImmediateParent
cellToChildren	Cell#Children Cell#ImmediateChildren
cellToCenterChild	Cell#CenterChild
compactCells	CompactCells
uncompactCells	UncompactCells
isResClassIII	Cell#IsResClassIII
isPentagon	Cell#IsPentagon
getIcosahedronFaces	Cell#IcosahedronFaces
areNeighborCells	Cell#IsNeighbor
cellsToDirectedEdge	Cell#DirectedEdge
isValidDirectedEdge	DirectedEdge#IsValid
getDirectedEdgeOrigin	DirectedEdge#Origin
getDirectedEdgeDestination	DirectedEdge#Destination
directedEdgeToCells	DirectedEdge#Cells
originToDirectedEdges	Cell#DirectedEdges
directedEdgeToBoundary	DirectedEdge#Boundary
cellToVertex	CellToVertex
cellToVertexes	CellToVertexes
vertexToLatLng	VertexToLatLng
isValidVertex	IsValidVertex
gridDistance	GridDistance, Cell#GridDistance
gridPathCells	GridPath, Cell#GridPath
cellToLocalIj	CellToLocalIJ
localIjToCell	LocalIJToCell

Conformance

Since v4.6 the package is pure Go; earlier v4 releases were a cgo binding to the C library. Its outputs are held to the H3 reference by the conformance suite in conformance/, whose README states the contract: discrete outputs (indexes, counts, booleans, errors, sets and sequences of indexes) are identical to the reference; coordinates agree within 1e-12 degrees of arc and measures within 1e-9 relative; knife-edge inputs, such as points on cell edges and polygon vertices on cell edges, are outside the contract. The suite's README also lists where this implementation deliberately differs from the reference.

The reference sources the suite is generated from are pinned as a git submodule at third_party/h3. They are needed only to regenerate the suite (git submodule update --init third_party/h3, then go generate ./conformance), never to build or test the package.

Contributing

Pull requests and Github issues are welcome. Please read our contributing guide for more information.

Legal and Licensing

H3-Go is licensed under the Apache 2.0 License.