sams96 / rgeo

Go package for basic, fast, local reverse geocoding

rgeo

Rgeo is a fast, simple solution for local reverse geocoding, Rather than relying on external software or online APIs, rgeo packages all of the data it needs in your binary. This means it will only ever work down to the level of cities , but if that's all you need then this is the library for you.

Rgeo uses data from naturalearthdata.com, if your coordinates are going to be near specific borders I would advise checking the data beforehand (links to which are in the files). If you want to use your own dataset, check out datagen.

Key Features

• Fast - So I haven't actually benchmarked other reverse geocoding tools but on my laptop rgeo can run at under 800ns/op.
• Local - Rgeo doesn't require pinging some API, most of which either cost money to use or have severe rate limits.
• Lightweight - The rgeo repo is 32MB, which is large for a Go package but compared to the 800GB needed for a full planet install of Nominatim it's miniscule.

Installation

Download with

go get github.com/sams96/rgeo

and add

import "github.com/sams96/rgeo"

to the top of your Go file to include it in your project.

Usage

r, err := New(Provinces10, Cities10)
if err != nil {
	// Handle error
}

loc, err := r.ReverseGeocode([]float64{141.35, 43.07})
if err != nil {
	// Handle error
}

fmt.Println(loc)
// Output: <Location> Sapporo, Hokkaidō, Japan (JPN), Asia

First initialise rgeo using rgeo.New,

func New(datasets ...func() []byte) (*Rgeo, error)

which takes any non-zero number of datasets as arguments. The included datasets are:

• Countries110 - Just country information, smallest and lowest detail of the included datasets.
• Countries10 - The same as above but with more detail.
• Provinces10 - Includes province information as well as country, so can still be used alone.
• Cities10 - Just city information, if you want provinces and/or countries as well use one of the above datasets with it. Once initialised you can use ReverseGeocode on the value returned by New, with your coordinates to get the location information. See the Go Docs for more information on usage.

Then use ReverseGeocode to get the location information of the given coordinate.

func (r *Rgeo) ReverseGeocode(loc geom.Coord) (Location, error)

The input is a geom.Coord, which is just a []float64 with the longitude in the zeroth position and the latitude in the first position (i.e. []float64{lon, lat}). ReverseGeocode returns a Location, which looks like this:

type Location struct {
	// Commonly used country name
	Country string `json:"country,omitempty"`

	// Formal name of country
	CountryLong string `json:"country_long,omitempty"`

	// ISO 3166-1 alpha-1 and alpha-2 codes
	CountryCode2 string `json:"country_code_2,omitempty"`
	CountryCode3 string `json:"country_code_3,omitempty"`

	Continent string `json:"continent,omitempty"`
	Region    string `json:"region,omitempty"`
	SubRegion string `json:"subregion,omitempty"`

	Province string `json:"province,omitempty"`

	// ISO 3166-2 code
	ProvinceCode string `json:"province_code,omitempty"`

	City string `json:"city,omitempty"`
}

So, to put it all together:

r, err := rgeo.New(Countries110)
if err != nil {
	// Handle error
}

loc, err := r.ReverseGeocode([]float64{0, 52})
if err != nil {
	// Handle error
}

fmt.Printf("%s\n", loc.Country)
fmt.Printf("%s\n", loc.CountryLong)
fmt.Printf("%s\n", loc.CountryCode2)
fmt.Printf("%s\n", loc.CountryCode3)
fmt.Printf("%s\n", loc.Continent)
fmt.Printf("%s\n", loc.Region)
fmt.Printf("%s\n", loc.SubRegion)

// Output: United Kingdom
// United Kingdom of Great Britain and Northern Ireland
// GB
// GBR
// Europe
// Europe
// Northern Europe

Contributing

Contributions are welcome, I haven't got any guidelines or anything so maybe just make an issue first.

Projects using rgeo

• rgeoSrv - rgeo as a microservice

rgeo's Issues

Add support for subdivisions & cities

Should be optional, since it requires a lot more data. Hopefully go will automatically compile with only the data set in use so I can include them all in the project without making huge binaries when the larger datasets aren't needed.

tzdata?

I want to get US and Canada regions like east/west/midwest. The countries databases are too coarse and the cities&provinces databases are too fine. Is it possible to include the natural earth timezone database and from there I can get a nice granularity that I'm looking for? If not I can just build a hash of the subregions from the cities database I guess.

https://www.naturalearthdata.com/downloads/10m-cultural-vectors/timezones/

nearly 2MB, which isn't too bad. I'm doubtful that the TZ database contains details like cities that don't conform to daylight savings, so it would be misleading that way, but for my purpose it would be great.

Add city and province information to Location printing

Location.String() hasn't been updated to include city and province information.

Replace `datagen` with go embed

Check bounds before checking the full geometry

It seems like it would be quicker to check if the point is within the bounds of each country before checking the geometry.

Documentation available on pkg.go.dev

Hello!

I work on pkg.go.dev, and we received a bug asking the the following:

My projects (github.com/sams96/rgeo) documentation hasn't updated for the last 2 releases.

I wanted to let you know that the latest versions of your project should be available on pkg.go.dev. You can see all of the available versions here:

https://pkg.go.dev/mod/github.com/sams96/rgeo?tab=versions

We monitor the Go Module Index regularly for new packages to add to pkg.go.dev. If you don’t see a package on pkg.go.dev, you can add it by:

1. Making a request to proxy.golang.org for the module version:

• For example, https://proxy.golang.org/github.com/sams96/rgeo/@v/v1.0.0.info

2. Downloading the package via the go command:

• For example, GO111MODULE=on go get <package>

Documentation is generated based on Go source code downloaded from the proxy.golang.org/<module>@<version>.zip. New packages and modules are added to pkg.go.dev every few minutes.

Hope this helps!

JSON is unmarshalled every time

json.Unmarshal doesn't need to be run every time , it could just be run once and then the geojson.FeatureCollection can be passed around for each use.

Minimize RAM usage

EDIT: Just noticed the Countries110 dataset has a pretty low ram consumption, I think I will settle for that :). How different is it from Countries10?

Hi! I'm currently trying to use rgeo for a college assignment, which asks me to set up a social media server that supports reverse geolocation. I'm using a free hosting solution (fly.io) and because of that I need to minimize RAM usage, otherwise I will need to pay for the host :(

Is only loading the Countries10 dataset the best I can do? (doing that consumes about ~250MB of ram idling) .Including provinces and cities ramps up the usage to 10GB of ram according to my IDE profiler.

Thanks for the help and sorry for the very unrelated issue

Streamline & document using additional datasets

It's currently possible to use a data set not included in the package for your reverse geocoding, but I seem to have neglected to document the process and it's a bit annoying since you need to encode the data with the datagen script.

My proposal would be to:

• Remove the datagen script and just store the data in raw geojson
• Remove all but one of the included data sets, to compensate for the increased file size when not using the compression
• Make it really obvious how to use data sets that aren't included, as this would be the way you're expected to use the package.