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 dealing with geographical data a little bit easier.
documentation
You can read the documentation here.
usage
Import from github, and get geomancin'
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:
- Querying for points within a radius using your own SQL data tables.
- Transposing a point for a given distance and bearing.
- Calculating the Great Circle Distance bewteen two points.
- Geocoding an address using Google Maps API or Open Street Maps API.
- Reverse Geocoding a Point using the same services.
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
The project 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".
If you want to supply a custom database conifguration, feel free to do so by using the template below:
development:
driver: postgres
openStr: user=username password=password dbname=points sslmode=disable
table: points
latCol: lat
lngCol: lng
Or if you want to connect via MySQL, you can do that as well!
development:
driver: mysql
openStr: points/username/password
table: points
latCol: lat
lngCol: lng
Once you've supplied your configuration, you may connect to your database with the following line of code:
db, err := geo.HandleWithSQL()
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.
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 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
- Create a topic branch
- Make dem commits!
- Write dem tests!
- Submit Pull Request once Tests are Passing
- do this (づ￣ ³￣)づ
Thanks! ｡◕‿◕｡
Documentation
¶
Index ¶
Constants ¶
const ( DEFAULT_PGSQL_OPEN_STR = "user=postgres dbname=points sslmode=disable" DEFAULT_MYSQL_OPEN_STR = "points/root/" DEFAULT_TEST_OPEN_STR = "" )
const (
EARTH_RADIUS = 6371 // Earth's radius ~= 6,371km, according to wikipedia
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Geocoder ¶
type Geocoder interface {
Geocode(query string) (*Point, error)
ReverseGeocode(p *Point) (string, error)
}
This interface describes a Geocoder, which provides the ability to Geocode and Reverse Geocode geographic points of interest. Geocoding should accept a string that represents a street address, and returns a pointer to a Point that most closely identifies it. Reverse geocoding should accept a pointer to a Point, and return the street address that most closely represents it.
type GoogleGeocoder ¶
type GoogleGeocoder struct{}
func (*GoogleGeocoder) Geocode ¶
func (g *GoogleGeocoder) Geocode(query string) (*Point, error)
Geocodes the passed in query string and returns a pointer to a new Point struct. Returns an error if the underlying request cannot complete.
func (*GoogleGeocoder) Request ¶
func (g *GoogleGeocoder) Request(params string) ([]byte, error)
Issues a request to the google geocoding service and forwards the passed in params string as URL-encoded entities. Returns an array of byes as a result, or any error incurred along the way
func (*GoogleGeocoder) ReverseGeocode ¶
func (g *GoogleGeocoder) ReverseGeocode(p *Point) (string, error)
Reverse geocodes the pointer to a Point struct and returns the first address that matches or returns an error if the underlying request cannot complete.
type MapQuestGeocoder ¶
type MapQuestGeocoder struct {
}
A Geocoder that makes use of open street map's geocoding service
func (*MapQuestGeocoder) Geocode ¶
func (g *MapQuestGeocoder) Geocode(query string) (*Point, error)
Use MapQuest's open service for geocoding @param [String] str. The query in which to geocode.
func (*MapQuestGeocoder) ReverseGeocode ¶
func (g *MapQuestGeocoder) ReverseGeocode(p *Point) (string, error)
type Mapper ¶
This interface describes a Mapper, which should be a data storage mechanism that can execute interesting queries. Currently, mappers should be able to find points within a radius of an origin point.
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) GreatCircleDistance ¶
Calculates the Haversine distance between two points. 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 of transposing the origin point the distance (in meters) supplied by the compass bearing (in degrees) supplied. Original Implementation from: http://www.movable-type.co.uk/scripts/latlong.html
type SQLConf ¶
type SQLConf struct {
// contains filtered or unexported fields
}
Provides a set of configuration variables that describe how to interact with a SQL database.
func GetSQLConf ¶
Attempts to read config/geo.yml, and creates a SQLConf as described therein. Returns the DefaultSQLConf if no config/geo.yml is found, or an error if one arises during the process of parsing the configuration file.
type SQLMapper ¶
type SQLMapper struct {
// contains filtered or unexported fields
}
A Mapper that uses Standard SQL Syntax to perform mapping functions and queries
func HandleWithSQL ¶
Retrieves the SQL configuration specified in the config.yml file that resides at the root level of the project. Returns a pointer to a SQLMapper if successful, or an error if there is an issue opening a database connection.
func (*SQLMapper) PointsWithinRadius ¶
Uses SQL to retrieve all points within the radius (in meters) passed in from the origin point passed in. Original implemenation from : http://www.movable-type.co.uk/scripts/latlong-db.html Returns a pointer to a sql.Rows as a result, or an error if one occurs during the query.
Source Files