H3-Go

This library provides Golang bindings for the H3 Core Library. For API reference, please see the H3 Documentation.

Usage

Prerequisites

H3-Go requires CGO (CGO_ENABLED=1) in order to be built. Generally, 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 for your build step.

Installation

golang/dep

dep ensure -add github.com/uber/h3-go

Note: h3-go includes non-go directories that, by default, dep will prune. You can prevent this by including the following prune directive in your Gopkg.toml:

[prune]
	[[prune.project]]
		name = "github.com/uber/h3-go"
		non-go = false
		unused-packages = false

golang/cmd/go

go get github.com/uber/h3-go

Glide

glide install github.com/uber/h3-go

Quickstart

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

func ExampleFromGeo() {
	geo := h3.GeoCoord{
		Latitude:  37.775938728915946,
		Longitude: -122.41795063018799,
	}
	resolution := 9
	fmt.Printf("%#x\n", h3.FromGeo(geo, resolution))
	// Output:
	// 0x8928308280fffff
}

Notes

API Differences

All GeoCoord structs return Latitude and Longitude as degrees, instead of radians.

Some superficial changes have been made relative to the H3 C core API in order to adhere to idiomatic Go styling. Most notable are the following:

H3 C API function prefixes of H3 have been dropped to reduce stutter in usage, e.g. h3.ToGeo(h).
H3 C functions that convert to H3Index have their names inverted to convert from something else to H3Index, e.g. GeoToH3 is renamed to h3.FromGeo.
H3 C API function prefixes of Get have been dropped in support of Golang's Getter naming style.

CGO

The H3 C source code and header files are copied into this project to optimize for portability. By including the C source files in the h3 Go package, there is no need to introduce a build process or a system dependency on an H3 binary. Effectively, this decision makes h3 as easy to use in a Go project as adding it as a dependency with your favorite dependency manager.

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.

twz915 / h3-go