H3-Go is looking for a maintainer familiar with Go, C, and H3. Volunteers welcome! Please get in touch with us on the H3 Slack.

H3-Go

This library provides Golang bindings for the H3 Core Library. 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

Prerequisites

H3-Go requires CGO (CGO_ENABLED=1) in order to be built. Go should do the right thing when including this library:

The cgo tool is enabled by default for native builds on systems where it is expected to work. It is disabled by default when cross-compiling. You can control this by setting the CGO_ENABLED environment variable when running the go tool: set it to 1 to enable the use of cgo, and to 0 to disable it. The go tool will set the build constraint "cgo" if cgo is enabled. The special import "C" implies the "cgo" build constraint, as though the file also said "// +build cgo". Therefore, if cgo is disabled, files that import "C" will not be built by the go tool. (For more about build constraints see https://golang.org/pkg/go/build/#hdr-Build_Constraints).

If you see errors/warnings like "build constraints exclude all Go files...", then the cgo build constraint is likely disabled; try setting CGO_ENABLED=1 environment variable in your go build step.

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 := h3.LatLngToCell(latLng, resolution)

 fmt.Printf("%s", 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`
`gridDiskDistances`	`GridDiskDistances`, `Cell#GridDiskDistances`
`gridRingUnsafe`	N/A
`polygonToCells`	`PolygonToCells`, `GeoPolygon#Cells`
`cellsToMultiPolygon`	TODO
`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`	TODO
`cellToVertexes`	TODO
`vertexToLatLng`	TODO
`isValidVertex`	TODO
`gridDistance`	`GridDistance`, `Cell#GridDistance`
`gridPathCells`	`GridPath`, `Cell#GridPath`
`cellToLocalIj`	`CellToLocalIJ`
`localIjToCell`	`LocalIJToCell`

CGO

The H3 C source code and header files are copied into this project to optimize for portability. h3-go can be imported into any Go project for any platform that CGO supports.

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.

SoulPancake/h3-go