https://github.com/sams96/rgeo
Go package for basic, fast, local reverse geocoding
https://github.com/sams96/rgeo
geo geolocation go golang golang-package reverse-geocoding rgeo
Last synced: 3 days ago
JSON representation
Go package for basic, fast, local reverse geocoding
- Host: GitHub
- URL: https://github.com/sams96/rgeo
- Owner: sams96
- License: apache-2.0
- Created: 2020-02-14T18:36:08.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2025-04-21T16:44:35.000Z (9 months ago)
- Last Synced: 2025-08-15T06:51:36.469Z (5 months ago)
- Topics: geo, geolocation, go, golang, golang-package, reverse-geocoding, rgeo
- Language: Go
- Homepage: https://pkg.go.dev/github.com/sams96/rgeo
- Size: 71.7 MB
- Stars: 62
- Watchers: 1
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# rgeo
[](https://github.com/sams96/rgeo/actions?query=workflow%3Acontinuous-integration)
[](https://goreportcard.com/report/github.com/sams96/rgeo)
[](https://codecov.io/gh/sams96/rgeo)
[](https://github.com/sams96/rgeo/releases/latest)
[](https://pkg.go.dev/github.com/sams96/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](https://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](https://github.com/sams96/rgeo/tree/master/datagen).
## Current status
Rgeo is not being activly developed. I will try to keep dependencies up to date
but no new features will be added. You can read more
[here](https://sams96.github.io/rgeo-5-years-on) if you are interested. If you
are looking for an alternative, I recommend:
- [smilyorg/tinygpkg](https://github.com/smilyorg/tinygpkg) - Very nice package
inspired by Rgeo. It uses a different approach to vastly reduce startup time at
the cost of slightly slower queries.
- [authenticvision/rgeo](https://github.com/authenticvision/rgeo) - The most
active fork of Rgeo, and most of the contributions I’ve had have come from
these guys.
Otherwise it should be fine to keep using Rgeo with its existing features.
## 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](https://nominatim.org/release-docs/latest/admin/Installation/#hardware)
it's miniscule.
## Installation
Download with
go get github.com/sams96/rgeo
and add
```go
import "github.com/sams96/rgeo"
```
to the top of your Go file to include it in your project.
## Usage
```go
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: Sapporo, Hokkaidō, Japan (JPN), Asia
```
First initialise rgeo using `rgeo.New`,
```go
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](https://pkg.go.dev/github.com/sams96/rgeo) for more information on usage.
Then use `ReverseGeocode` to get the location information of the given coordinate.
```go
func (r *Rgeo) ReverseGeocode(loc geom.Coord) (Location, error)
```
The input is a [`geom.Coord`](https://github.com/twpayne/go-geom), 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:
```go
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:
```go
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
I'm not accepting new features for the time being, see above.