Geographical calculations in Go.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
db Adding an additional configuration key such that goose migrations can… Jan 25, 2014
test/data Fixing type errors; mapquest currently only sends strings back from i… May 10, 2015
.gitignore Adding *.html files to .gitignore so that the output of testing cover… Jan 20, 2014
.travis.yml build: updating travis.yml to explicity dl goose/lib before goose/cmd Sep 28, 2015 changelog: Adding in notes for v0.7.0 release Dec 8, 2015
MIT_LICENSE [file][test] Fixing some broken tests, fixing file permissoins that s… Mar 16, 2013 Fix typo in README. Dec 9, 2015 Adding some more clarification to the May 10, 2015
VERSION Bumping VERSION to 0.6.1 Jun 24, 2015
geo.go Adding in a NewSQLMapper method such that consumers of the library ca… Jan 19, 2014
geo_test.go Converting EARTH_RADIUS to a float64 before sprintfing it into queries Jan 20, 2014
geocoder.go [src] Adding some documentation to the geocoder.go interface Sep 17, 2013
google_geocoder.go Google geocoder should use HTTPS in the request URL, not HTTP Jun 24, 2015
google_geocoder_test.go Applying go fmt May 10, 2015
mapper.go [src] Adding some documentation to the mapper.go interface Sep 17, 2013
mapquest_geocoder.go Applying go fmt May 10, 2015
mapquest_geocoder_test.go Applying go fmt May 10, 2015
opencage_geocoder.go Applying go fmt May 10, 2015
opencage_geocoder_test.go Applying go fmt May 10, 2015
point.go add missing import Dec 4, 2015
point_test.go Unit tests for Point.MarshalBinary() and Point.UnmarshalBinary(). Dec 10, 2015
polygon.go use Point's lat/lng in package instead of getters; return point value… Jan 14, 2015
polygon_test.go Running gofmt before release Apr 30, 2014
sql_conf.go Fixing some conflicting mismatch issues with sql configuration files … Jan 20, 2014
sql_conf_test.go run go fmt Feb 8, 2014
sql_mapper.go Merge branch 'earth-radius-fix' into develop Jan 25, 2014
sql_mapper_test.go run go fmt Feb 8, 2014

             /\_ \                                                             
   __     ___\//\ \      __      ___      __               __      __    ___   
 /'_ `\  / __`\\ \ \   /'__`\  /' _ `\  /'_ `\  _______  /'_ `\  /'__`\ / __`\ 
/\ \L\ \/\ \L\ \\_\ \_/\ \L\.\_/\ \/\ \/\ \L\ \/\______\/\ \L\ \/\  __//\ \L\ \
\ \____ \ \____//\____\ \__/.\_\ \_\ \_\ \____ \/______/\ \____ \ \____\ \____/
 \/___L\ \/___/ \/____/\/__/\/_/\/_/\/_/\/___L\ \        \/___L\ \/____/\/___/ 
   /\____/                                /\____/          /\____/             
   \_/__/                                 \_/__/           \_/__/              

♫ around the world ♪

Build Status Coverage Status GoDoc Join the chat at


This library provides convenience functions for translating, geocoding, and calculating distances between geographical points. It is inspired by ruby's geokit and geokit-rails gems, and aims to make working with geographical data a little bit easier in golang.


You can read the documentation here.


Import from github to get started!

package main


func main() {
     // Make a few points
     p := geo.NewPoint(42.25, 120.2)
     p2 := geo.NewPoint(30.25, 112.2)
     // find the great circle distance between them
     dist := p.GreatCircleDistance(p2)
     fmt.Printf("great circle distance: %d\n", dist)

Currently, golang-geo provides the following functionality:

  • Transposing a point for a given distance and bearing.
  • Calculating the Great Circle Distance between two points.
  • Geocoding an address using Google Maps, Mapquest (OpenStreetMap data), OpenCage (OpenStreetMap, twofishes and other data sources) API.
  • Reverse Geocoding a Point using the same services.
  • Querying for points within a radius using your own SQL data tables.

Keep in mind that you do not need to use SQL in order to perform simple Point operations and the only function that relies on SQL is PointsWithinRadius.

using SQL

As of 0.1.0, golang-geo will shift its scope of responsiblity with SQL management. The library will still support the functions exposed in its public API in the past, however, it will not concern itself so much with creating and maintaining *sql.DB connections as it has done in previous versions. It is suggested that if you are using geo.HandleWithSql that you should instead consider creating a geo.SQLMapper yourself by calling the newly introduced geo.NewSQLMapper method, which accepts a *sql.DB connection and a filepath to the configuration file used to inform golang-geo of your particular SQL setup.

That being said, geo.HandleWithSQL is configured to connect to a SQL database by reading a config/geo.yml file in the root level of your project. If it does not exist, it will use a Default SQL configuration that will use the postgres driver as described by lib/pq. The Default SQL configuration will attempt to connect as a user named "postgres" and with the password "postgres" to a database named "points".

examples of SQL database configurations

Here are some examples of valid config files that golang-geo knows how to process:

  driver: postgres
  openStr: user=username password=password dbname=points sslmode=disable
  table: points
  latCol: lat
  lngCol: lng
  driver: mysql
  openStr: points/username/password
  table: points
  latCol: lat
  lngCol: lng  


  • golang-geo currently only uses metric measurements to do calculations
  • The $GO_ENV environment variable is used to determine which configuration group in config.yml is to be used. For example, if you wanted to use the PostgreSQL configuration listed above, you could specify GO_ENV=development which would read config.yml and use the configuration under the root-level key development.

installing older versions of golang-geo

With the advent of, you can now install older versions of golang-geo! Consult for the version you wish to build against.


  • More Tests!
  • Redis / NOSQL Mapper
  • Bing Maps?
  • Add an abstraction layer for PostgreSQL earthdistance / PostGIS


By default, golang-geo will attempt to run its test suite against a PostgreSQL database. However, you may run the tests with mocked SQL queries by specifying that you want to do so on the command line:

DB=mock GO_ENV=test go test

The $DB environment variable is used to specify which database you'd like to run the tests against. You may specify postgres, mysql, or mock. The Travis CI builds for this project currently runs against all of these when running the test suite.


  • Fork the project
  • Create a topic branch (preferably the in the gitflow style of feature/, hotfix/, etc)
  • Make your changes and write complimentary tests to ensure coverage.
  • Submit Pull Request once the full test suite is passing.
  • Pull Requests will then be reviewed by the maintainer and the community and hopefully merged!