geo-golang

The chained package allows you to create a single geo.Geocoder that attempts to resolve a request using a sequence of providers. If one provider returns no result, the library automatically falls back to the next provider in the chain. This is useful for maximizing uptime and utilizing free quotas across multiple services.

import (
    "github.com/codingsince1985/geo-golang/chained"
    "github.com/codingsince1985/geo-golang/openstreetmap"
    "github.com/codingsince1985/geo-golang/google"
)

// Chained geocoder will fallback to subsequent geocoders
geocoder := chained.Geocoder(
    openstreetmap.Geocoder(),
    google.Geocoder(os.Getenv("GOOGLE_API_KEY")),
)

location, _ := geocoder.Geocode("Melbourne VIC")

Once you have a geo.Geocoder instance, you can perform two primary operations:

1. Geocoding: Convert a human-readable address into geographic coordinates (Latitude/Longitude).
2. Reverse Geocoding: Convert geographic coordinates into a structured geo.Address object.

Note: Always check if the returned location or address is nil to handle cases where the service could not find a match.

// Assuming 'geocoder' is an initialized geo.Geocoder

// 1. Geocoding
location, _ := geocoder.Geocode("Melbourne VIC")
if location != nil {
    fmt.Printf("Lat: %.6f, Lng: %.6f\n", location.Lat, location.Lng)
}

// 2. Reverse Geocoding
address, _ := geocoder.ReverseGeocode(-37.813611, 144.963056)
if address != nil {
    fmt.Printf("Address: %s\n", address.FormattedAddress)
    fmt.Printf("City: %s, Country: %s\n", address.City, address.Country)
}

The geo package uses two global loggers for error and debug reporting. You can replace these with your own logging implementation by satisfying the StdLogger interface.

• ErrLogger: Used for error messages. Defaults to io.Discard.
• DebugLogger: Used for debug messages. Defaults to io.Discard.

To customize logging, assign a new implementation to these variables:

type myLogger struct{}
func (l *myLogger) Printf(format string, v ...interface{}) { /* implementation */ }

geo.ErrLogger = &myLogger{}

var ErrLogger StdLogger = log.New(io.Discard, "[Geo][Err]", log.LstdFlags)
var DebugLogger StdLogger = log.New(io.Discard, "[Geo][Debug]", log.LstdFlags)

type StdLogger interface {
	Printf(string, ...interface{})
}

The library provides clients for a wide variety of geocoding providers. Each client is typically initialized with an API key or specific configuration parameters.

Supported providers include:

• Google Maps (google)
• Mapbox (mapbox)
• OpenStreetMap (openstreetmap)
• HERE (here)
• Bing (bing)
• MapQuest (mapquest/nominatim, mapquest/open)
• OpenCage (opencage)
• ArcGIS (arcgis)
• geocod.io (geocod)
• TomTom (tomtom)
• Yandex (yandex)
• Baidu (baidu)
• French API Gouv (frenchapigouv)
• LocationIQ (locationiq)
• PickPoint (pickpoint)
• Mapzen (mapzen)
• Amap (amap)
• Chained (chained - for fallback logic)

The ResponseUnmarshaler interface allows you to define how raw bytes from an HTTP response are converted into Go objects. HTTPGeocoder uses this to handle different content types.

Available implementations:

• JSONUnmarshaler: Trims whitespace and brackets before parsing JSON.
• XMLUnmarshaler: Standard XML unmarshaling.

You can provide your own implementation to the HTTPGeocoder.ResponseUnmarshaler field.

type ResponseUnmarshaler interface {
	Unmarshal(data []byte, v any) error
}

// Example of using the built-in JSON unmarshaler
var unmarshaler = &geo.JSONUnmarshaler{}

The HTTPGeocoder methods use a context with a timeout. If the request does not complete within the DefaultTimeout (8 seconds), the operation will return ErrTimeout.

DefaultTimeout is a constant of type time.Duration set to 8s.

const DefaultTimeout = time.Second * 8
var ErrTimeout = errors.New("TIMEOUT")

The Address struct is returned by ReverseGeocode. It provides a structured representation of a location, including specific fields for street, suburb, city, and country, as well as a FormattedAddress string.

type Address struct {
	FormattedAddress string
	Street           string
	HouseNumber      string
	Suburb           string
	Postcode         string
	State            string
	StateCode        string
	StateDistrict    string
	County           string
	Country          string
	CountryCode      string
	City             string
}

The ResponseParser interface is used to extract specific domain objects (Location or Address) from the unmarshaled response data. The HTTPGeocoder uses a factory pattern (ResponseParserFactory) to create a new parser for every request.

type ResponseParser interface {
	Location() (*Location, error)
	Address() (*Address, error)
}

type ResponseParserFactory func() ResponseParser

The Location struct represents a geographic point using latitude and longitude.

type Location struct {
	Lat, Lng float64
}

The Geocoder interface is the core abstraction for geocoding services. Any implementation must provide methods to convert an address string into coordinates (Geocode) and coordinates into a structured address (ReverseGeocode).

type Geocoder interface {
	Geocode(address string) (*Location, error)
	ReverseGeocode(lat, lng float64) (*Address, error)
}