h3-go

H3-Go requires CGO to be enabled (CGO_ENABLED=1) to build. If you encounter errors such as build constraints exclude all Go files..., it means CGO is likely disabled. You can explicitly enable it by setting the CGO_ENABLED environment variable during your build step.

CGO_ENABLED=1 go build

Install the H3-Go v4 library using go get. This version supports H3 v4.

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

The h3 package uses three primary types to represent different topological entities in the H3 grid:

• Cell: An int64 representing a single hexagon (or pentagon) at a specific resolution.
• DirectedEdge: An int64 representing a directed edge between two adjacent cells.
• Vertex: An int64 representing a topological vertex shared by three cells.

All three types implement the Index interface and can be converted to/from strings or hex representations.

Use h3.NewLatLng to create a latitude/longitude object and h3.LatLngToCell to convert it to an H3 cell at a specific resolution (0-15).

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

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
}

Use the Resolution() method on a Cell to retrieve its H3 resolution level (typically an integer between 0 and 15).

res := cell.Resolution()

Use v.LatLng() or VertexToLatLng(v Vertex) to get the latitude and longitude of a Vertex. Returns a LatLng struct containing Lat and Lng fields.

latLng, err := vertex.LatLng()
if err != nil {
    // Handle error
}
fmt.Printf("Lat: %f, Lng: %f\n", latLng.Lat, latLng.Lng)

To visualize a set of H3 cells as a geographic shape, use CellsToMultiPolygon. This returns a slice of GeoPolygon objects describing the outlines of the hexagons. It is expected that all input cells have the same resolution and no duplicates.

polygons, err := h3.CellsToMultiPolygon(cells)

The generic function IsValidIndex[T Index](index T) checks if a given H3 index (of type Cell, DirectedEdge, or Vertex) is valid.

• For Cell, validation is performed via pure Go bit manipulation.
• For DirectedEdge and Vertex, validation calls through to CGo as it requires coordinate geometry.

if IsValidIndex(myCell) {
    // cell is valid
}

Use the NumCells(res int) function to get the total number of H3 cells existing at a specific resolution. If the provided resolution is outside the valid range [0, maxResolution], the function returns 0.

count := h3go.NumCells(5)

To find the H3 Cell that contains a specific geographic coordinate, use LatLngToCell or the Cell method on a LatLng struct. You must specify the desired resolution (0-15).

// Using the helper function
cell, err := h3.LatLngToCell(h3.NewLatLng(37.7749, -122.4194), 9)

// Or using the method on LatLng
latLng := h3.LatLng{Lat: 37.7749, Lng: -122.4194}
cell, err := latLng.Cell(9)