geocollection

README

Location-Based Collection for Go

geocollection builds on top of Google's S2 Library to provide a location-based collection for Go. With this library you can store data based on latitude and longitude. Once it is stored, you may retrieve items within a specific distance by supplying another latitude and longitude.

The library also exposes fine-grained controls over the covering parameters used by S2 to provide maximum performance tuning.

API documentation and examples can be found in the GoDoc.

Linting

Run the linter using the command make lint.

A common linting error is the fieldalignment warning from the govet analyzer. fieldalignment errors arise when the order of a struct’s fields could be arranged differently to optimize the amount of allocated memory.

Imagine the following struct:

type MyObject struct {
    myBool   bool
    myString string
}

Running the linter would produce this output:

>> make lint
golangci-lint run

main.go:16:15: fieldalignment: struct with 16 pointer bytes could be 8 (govet)
type MyObject struct {
              ^
make: *** [lint] Error 1

The struct is more optimally arranged as:

type MyObject struct {
    myString string
    myBool   bool
}

A fieldalignment command line tool exists to help optimally arrange all the structs in a given file or package. Note that this tool will remove all existing comments within any structs it rearranges. Be sure to manually re-add any deleted comments after running the command.

Installation:

go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest

Utilization:

fieldalignment -fix {PATH_TO_FILE_OR_PACKAGE}

License

Apache 2

Documentation

Overview

Package geocollection provides a data structure for storing and quickly searching for items based on geographic coordinates on Earth.

Index

• Constants
• func EarthDistanceMeters(p1, p2 s2.Point) float64
• func NewPointFromLatLng(latitude, longitude float64) s2.Point
• type Collection
  • func NewCollection() Collection
  • func (c Collection) Delete(key interface{})
  • func (c Collection) GetItems(pageSize, startIndex int) []interface{}
  • func (c Collection) ItemByKey(key interface{}) interface{}
  • func (c Collection) ItemsWithinDistance(latitude, longitude, distanceMeters float64, params SearchCoveringParameters) ([]interface{}, SearchCoveringResult)
  • func (c Collection) Set(key, contents interface{}, latitude, longitude float64)
• type LocationCollection
• type SearchCoveringParameters
• type SearchCoveringResult

Constants

const EarthRadiusMeters = 6371008.8

EarthRadiusMeters is an approximate representation of the earth's radius in meters.

Functions

func EarthDistanceMeters

func EarthDistanceMeters(p1, p2 s2.Point) float64

EarthDistanceMeters calculates the distance in meters between two points on the surface of the Earth

func NewPointFromLatLng

func NewPointFromLatLng(latitude, longitude float64) s2.Point

NewPointFromLatLng constructs an s2 point from a lat/lon ordered pair

Types

type Collection

type Collection struct {
	// contains filtered or unexported fields
}

Collection implements the GeoLocationCollection interface and provides a location based cache

func NewCollection

func NewCollection() Collection

NewCollection creates a new collection

func (Collection) Delete

func (c Collection) Delete(key interface{})

Delete removes an item by its key from the collection.

func (Collection) GetItems

func (c Collection) GetItems(pageSize, startIndex int) []interface{}

GetItems get the items form the collection based on arg pageSize, startIndex

func (Collection) ItemByKey

func (c Collection) ItemByKey(key interface{}) interface{}

ItemByKey returns the contents stored in the collection by its key instead of by a geolocation lookup

func (Collection) ItemsWithinDistance

func (c Collection) ItemsWithinDistance(
	latitude, longitude, distanceMeters float64, params SearchCoveringParameters,
) ([]interface{}, SearchCoveringResult)

ItemsWithinDistance returns all contents stored in the collection within distanceMeters radius from the provided latitude an longitude. Note that this is an approximation and items further than distanceMeters may be returned, but it is guaranteed that all item ids returned are within distanceMeters. The caller of this function must specify all parameters used to generate cell covering as well as whether or not the coverer will use the standard covering algorithm or the fast covering algorithm which may be less precise.

func (Collection) Set

func (c Collection) Set(key, contents interface{}, latitude, longitude float64)

Set adds an item with a given key to the geo collection at a particular latitude and longitude. If the given key already exists in the collection, it is created, otherwise the contents and location is updated to the new values.

type LocationCollection

type LocationCollection interface {
	Set(key, contents interface{}, latitude, longitude float64)
	Delete(key interface{})
	ItemsWithinDistance(latitude, longitude, distanceMeters float64, params SearchCoveringParameters) ([]interface{}, SearchCoveringResult)
	ItemByKey(key interface{}) interface{}
	GetItems(pageSize, startIndex int) []interface{}
}

LocationCollection defines the interface for interacting with Geo-based collections

type SearchCoveringParameters

type SearchCoveringParameters struct {
	LevelMod        int  `json:"level_mod"`
	MaxCells        int  `json:"max_cells"`
	MaxLevel        int  `json:"max_level"`
	MinLevel        int  `json:"min_level"`
	UseFastCovering bool `json:"use_fast_covering"`
}

SearchCoveringParameters controls the algorithm and parameters used by S2 to determine the covering for the requested search area

type SearchCoveringResult

type SearchCoveringResult [][][]float64

SearchCoveringResult are the boundaries of the cells used in the requested search