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 as well as
when the CC environment variable is unset and the default C compiler (typically
gcc or clang) cannot be found on the system PATH. You can override the default
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 "//go: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://pkg.go.dev/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/v4Quickstart
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
LatLngreturnsLatandLngas degrees, instead of radians.- H3 C API function prefixes of
gethave been dropped in support of Golang's
Getter naming style.
- Convenience methods have been added to various types where that type was the
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 |
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.