olc

README

Formatting

Go files must be formatted with gofmt, and the tests will check that this is the case. If the files are not correctly formatted, the tests will fail.

You can format your files by running:

gofmt -w -s .

Testing

Run the unit tests from within the go directory with:

go test . -v

To also run the benchmark tests, run:

go test -bench=. . -v

Test with Go-Fuzz

go get github.com/dvyukov/go-fuzz/...

go generate github.com/google/open-location-code/go

go-fuzz-build github.com/google/open-location-code/go
go-fuzz -bin=./olc-fuzz.zip -workdir=/tmp/olc-fuzz

Install

go get github.com/google/open-location-code/go

Documentation

Overview

Package olc implements the Open Location Code algorithm to convert latitude and longitude coordinates into a shorter sequence of letters and numbers.

The aim is to provide something that can be used like an address in locations that lack them, because the streets are unnamed.

Codes represent areas, and the size of the area depends on the length of the code. The typical code length is 10 digits, and represents an area of 1/8000 x 1/8000 degrees, or roughly 13.75 x 13.75 meters.

See https://github.com/google/open-location-code.

Index

• Constants
• Variables
• func Check(code string) error
• func CheckFull(code string) error
• func CheckShort(code string) error
• func Encode(lat, lng float64, codeLen int) string
• func RecoverNearest(code string, lat, lng float64) (string, error)
• func Shorten(code string, lat, lng float64) (string, error)
• func StripCode(code string) string
• type CodeArea
  • func Decode(code string) (CodeArea, error)
  • func (area CodeArea) Center() (lat, lng float64)

Constants

const (
	// Separator is the character that separates the two parts of location code.
	Separator = '+'
	// Padding is the optional (left) padding character.
	Padding = '0'

	// Alphabet is the set of valid encoding characters.
	Alphabet = "23456789CFGHJMPQRVWX"
)

const MinTrimmableCodeLen = 6

MinTrimmableCodeLen is the minimum length of a code that is able to be shortened.

Variables

var (
	// ErrShort indicates the provided code was a short code.
	ErrShort = errors.New("short code")
	// ErrNotShort indicates the provided code was not a short code.
	ErrNotShort = errors.New("not short code")
)

Functions

func Check

func Check(code string) error

Check checks whether the passed string is a valid OLC code. It could be a full code (8FVC9G8F+6W), a padded code (8FVC0000+) or a code fragment (9G8F+6W).

func CheckFull

func CheckFull(code string) error

CheckFull checks whether the passed string is a valid full code. If it is short, it returns ErrShort.

func CheckShort

func CheckShort(code string) error

CheckShort checks whether the passed string is a valid short code. If it is valid full code, then it returns ErrNotShort.

func Encode

func Encode(lat, lng float64, codeLen int) string

Encode a location into an Open Location Code.

Produces a code of the specified codeLen, or the default length if codeLen < 8; if codeLen is odd, it is incremented to be even.

latitude is signed decimal degrees. Will be clipped to the range -90 to 90. longitude is signed decimal degrees. Will be normalised to the range -180 to 180. The length determines the accuracy of the code. The default length is 10 characters, returning a code of approximately 13.5x13.5 meters. Longer codes represent smaller areas, but lengths > 14 are sub-centimetre and so 11 or 12 are probably the limit of useful codes.

func RecoverNearest

func RecoverNearest(code string, lat, lng float64) (string, error)

RecoverNearest recovers the nearest matching code to a specified location.

Given a short Open Location Code with from four to eight digits missing, this recovers the nearest matching full code to the specified location.

func Shorten

func Shorten(code string, lat, lng float64) (string, error)

Shorten removes characters from the start of an OLC code.

This uses a reference location to determine how many initial characters can be removed from the OLC code. The number of characters that can be removed depends on the distance between the code center and the reference location.

The minimum number of characters that will be removed is four. At most eight characters will be removed.

The reference location must be within 50% of the maximum range. This ensures that the shortened code will be able to be recovered using slightly different locations.

func StripCode

func StripCode(code string) string

StripCode strips the padding and separator characters from the code.

The code is truncated to the first 15 digits, as Decode won't use more, to avoid underflow errors.

Types

type CodeArea

type CodeArea struct {
	LatLo, LngLo, LatHi, LngHi float64
	Len                        int
}

CodeArea is the area represented by a location code.

func Decode

func Decode(code string) (CodeArea, error)

Decode decodes an Open Location Code into the location coordinates. Returns a CodeArea object that includes the coordinates of the bounding box - the lower left, center and upper right.

Longer codes are allowed, but only the first 15 is decoded.

func (CodeArea) Center

func (area CodeArea) Center() (lat, lng float64)

Center returns the (lat,lng) of the center of the area.