regionagogo

README

Region à gogo is a microservice, it's a simple database that returns metadata associated to a fence for a given location.

It uses S2 and a segment tree to create a fast geo shape database, details of implementation are described in this blog post.

It can also be used directly from docker docker run -P akhenakh/regionagogo

Data

You can use any geo data but the provided GeoJSON comes from who's on first.

It works too with Gadm Data but the data are not free for commercial use.

Regionagogo is using a BoltDB datafile to store the fences and a small segment tree as index lives in memory.

Build & Install

go get github.com/akhenakh/regionagogo
cd $GOPATH/src/github.com/akhenakh/regionagogo
make

To generate the database from GeoJSON use the provided ragogenfromjson command, you can specify the fields you want from the GeoJSON properties to be saved into the DB:

ragogenfromjson -filename testdata/world_region.geojson -importFields iso -dbpath ./region.db

Usage

Run regionagogo -dbpath ./region.db, it will listen on port 8082.

You can query via HTTP GET:

GET /query?lat=19.542915&lng=-155.665857

{
    "code": "US",
    "name": "Hawaii"
}

Using it as a library

You can use it in your own code without the HTTP interface:

gs := regionagogo.NewGeoSearch("region.db")
r := gs.StabbingQuery(msg.Latitude, msg.Longitude)

TODO

• create a struct for data import, change the default coverer ...
• move the cache outside of boltdb storage to make it generic
• implement an in memory storage

Documentation

Index

• type BySize
  • func (d BySize) Len() int
  • func (d BySize) Less(i, j int) bool
  • func (d BySize) Swap(i, j int)
• type Fence
  • func NewFenceFromStorage(rs *geostore.FenceStorage) *Fence
  • func (f *Fence) ToGeoJSON() *geojson.FeatureCollection
• type Fences
  • func (f *Fences) ToGeoJSON() *geojson.FeatureCollection
• type GeoFenceDB
• type Import
  • func NewGeoJSONImport(gs GeoFenceDB, r io.Reader, importFields []string, ...) *Import
  • func (i *Import) Start() error
• type QueryOptions
• type QueryOptionsFunc
  • func WithMultipleFences(mf bool) QueryOptionsFunc
• type S2Interval
  • func (s *S2Interval) HighAtDimension(d uint64) int64
  • func (s *S2Interval) ID() uint64
  • func (s *S2Interval) LowAtDimension(d uint64) int64
  • func (s *S2Interval) OverlapsAtDimension(iv augmentedtree.Interval, d uint64) bool

Types

type BySize

type BySize []*Fence

func (BySize) Len

func (d BySize) Len() int

func (BySize) Less

func (d BySize) Less(i, j int) bool

func (BySize) Swap

func (d BySize) Swap(i, j int)

type Fence

type Fence struct {
	Data map[string]string `json:"data"`
	Loop *s2.Loop          `json:"-"`
}

Fence is an s2 represented FenceStorage it contains an S2 loop and the associated metadata

func NewFenceFromStorage

func NewFenceFromStorage(rs *geostore.FenceStorage) *Fence

NewFenceFromStorage returns a Fence from a FenceStorage Fence can be extended, FenceStorage is a protocol buffer instance

func (*Fence) ToGeoJSON

func (f *Fence) ToGeoJSON() *geojson.FeatureCollection

ToGeoJSON transforms a Region to a valid GeoJSON

type Fences

type Fences []*Fence

Fences a slice of *Fence (type used mainly to return one GeoJSON of the regions)

func (*Fences) ToGeoJSON

func (f *Fences) ToGeoJSON() *geojson.FeatureCollection

ToGeoJSON transforms a set of Fences to a valid GeoJSON

type GeoFenceDB

type GeoFenceDB interface {
	// returns a Fence by it's storage id
	FenceByID(loopID uint64) *Fence

	// returns the fence for the corresponding lat, lng coordinates
	StubbingQuery(lat, lng float64, opts ...QueryOptionsFunc) (Fences, error)

	// RectQuery perform rectangular query ur upper right bl bottom left
	RectQuery(urlat, urlng, bllat, bllng float64, opts ...QueryOptionsFunc) (Fences, error)

	// RadiusQuery is performing a radius query
	RadiusQuery(lat, lng, radius float64, opts ...QueryOptionsFunc) (Fences, error)

	// Store a Fence into the DB
	StoreFence(rs *geostore.FenceStorage, cover []uint64) error

	// Close the DB
	Close() error
}

GeoFenceDB is the main interface to store and query your geo database

type Import

type Import struct {
	FeatureImport bool
	// contains filtered or unexported fields
}

func NewGeoJSONImport

func NewGeoJSONImport(gs GeoFenceDB, r io.Reader, importFields []string, forceFields map[string]string, renameFields map[string]string) *Import

func (*Import) Start

func (i *Import) Start() error

type QueryOptions

type QueryOptions struct {
	// Returns all fences when multiple fences match
	MultipleFences bool
}

queryOptions used to pass options to DB queries

type QueryOptionsFunc

type QueryOptionsFunc func(*QueryOptions)

func WithMultipleFences

func WithMultipleFences(mf bool) QueryOptionsFunc

WithMultipleFences enable multi fences in responses

type S2Interval

type S2Interval struct {
	s2.CellID
	LoopIDs []uint64
}

S2Interval is a CellID interval conforms augmentedtree Interval interface

func (*S2Interval) HighAtDimension

func (s *S2Interval) HighAtDimension(d uint64) int64

HighAtDimension returns an integer representing the higher bound at the requested dimension.

func (*S2Interval) ID

func (s *S2Interval) ID() uint64

ID should be a unique ID representing this interval. This is used to identify which interval to delete from the tree if there are duplicates.

func (*S2Interval) LowAtDimension

func (s *S2Interval) LowAtDimension(d uint64) int64

LowAtDimension returns an integer representing the lower bound at the requested dimension.

func (*S2Interval) OverlapsAtDimension

func (s *S2Interval) OverlapsAtDimension(iv augmentedtree.Interval, d uint64) bool

OverlapsAtDimension should return a bool indicating if the provided interval overlaps this interval at the dimension requested.