The highest tagged major version is
README
¶
___
/\_ \
__ ___\//\ \ __ ___ __ __ __ ___
/'_ `\ / __`\\ \ \ /'__`\ /' _ `\ /'_ `\ _______ /'_ `\ /'__`\ / __`\
/\ \L\ \/\ \L\ \\_\ \_/\ \L\.\_/\ \/\ \/\ \L\ \/\______\/\ \L\ \/\ __//\ \L\ \
\ \____ \ \____//\____\ \__/.\_\ \_\ \_\ \____ \/______/\ \____ \ \____\ \____/
\/___L\ \/___/ \/____/\/__/\/_/\/_/\/_/\/___L\ \ \/___L\ \/____/\/___/
/\____/ /\____/ /\____/
\_/__/ \_/__/ \_/__/
♫ around the world ♪
what
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.
documentation
You can read the documentation here.
usage
Import from github to get started!
package main
import("github.com/kellydunn/golang-geo"
"fmt")
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:
PostgreSQL
development:
driver: postgres
openStr: user=username password=password dbname=points sslmode=disable
table: points
latCol: lat
lngCol: lng
MySQL
development:
driver: mysql
openStr: points/username/password
table: points
latCol: lat
lngCol: lng
notes
golang-geocurrently only uses metric measurements to do calculations- The
$GO_ENVenvironment variable is used to determine which configuration group inconfig.ymlis to be used. For example, if you wanted to use the PostgreSQL configuration listed above, you could specifyGO_ENV=developmentwhich would readconfig.ymland use the configuration under the root-level keydevelopment.
installing older versions of golang-geo
With the advent of gopkg.in, you can now install older versions of golang-geo! Consult CHANGELOG.md for the version you wish to build against.
roadmap
- More Tests!
- Redis / NOSQL Mapper
- Bing Maps?
- Add an abstraction layer for PostgreSQL earthdistance / PostGIS
testing
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.
contributing
- Fork the project
- Create a topic branch (preferably the in the
gitflowstyle offeature/,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!
Thanks!
Documentation
¶
Index ¶
- Constants
- type Point
- func (p *Point) BearingTo(p2 *Point) float64
- func (p *Point) GreatCircleDistance(p2 *Point) float64
- func (p *Point) Lat() float64
- func (p *Point) Lng() float64
- func (p *Point) MarshalBinary() ([]byte, error)
- func (p *Point) MarshalJSON() ([]byte, error)
- func (p *Point) MidpointTo(p2 *Point) *Point
- func (p *Point) PointAtDistanceAndBearing(dist float64, bearing float64) *Point
- func (p *Point) UnmarshalBinary(data []byte) error
- func (p *Point) UnmarshalJSON(data []byte) error
- type Polygon
Constants ¶
const (
// According to Wikipedia, the Earth's radius is about 6,371km
EARTH_RADIUS = 6371
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Point ¶
type Point struct {
// contains filtered or unexported fields
}
Represents a Physical Point in geographic notation [lat, lng].
func NewPoint ¶
Returns a new Point populated by the passed in latitude (lat) and longitude (lng) values.
func (*Point) BearingTo ¶
Calculates the initial bearing (sometimes referred to as forward azimuth) Original Implementation from: http://www.movable-type.co.uk/scripts/latlong.html
func (*Point) GreatCircleDistance ¶
Calculates the Haversine distance between two points in kilometers. Original Implementation from: http://www.movable-type.co.uk/scripts/latlong.html
func (*Point) MarshalBinary ¶
Renders the current point to a byte slice. Implements the encoding.BinaryMarshaler Interface.
func (*Point) MarshalJSON ¶
Renders the current Point to valid JSON. Implements the json.Marshaller Interface.
func (*Point) MidpointTo ¶
Calculates the midpoint between 'this' point and the supplied point. Original implementation from http://www.movable-type.co.uk/scripts/latlong.html
func (*Point) PointAtDistanceAndBearing ¶
Returns a Point populated with the lat and lng coordinates by transposing the origin point the passed in distance (in kilometers) by the passed in compass bearing (in degrees). Original Implementation from: http://www.movable-type.co.uk/scripts/latlong.html
func (*Point) UnmarshalBinary ¶
func (*Point) UnmarshalJSON ¶
Decodes the current Point from a JSON body. Throws an error if the body of the point cannot be interpreted by the JSON body
type Polygon ¶
type Polygon struct {
// contains filtered or unexported fields
}
A Polygon is carved out of a 2D plane by a set of (possibly disjoint) contours. It can thus contain holes, and can be self-intersecting.
func NewPolygon ¶
Creates and returns a new pointer to a Polygon composed of the passed in points. Points are considered to be in order such that the last point forms an edge with the first point.
Source Files
Directories