Documentation
¶
Overview ¶
Package mapsurl turns any user-supplied location string into a Google Maps URL.
It accepts free-form addresses (any script), decimal or DMS coordinates, Open Location Codes (plus codes), geo: URIs, links from Google/Apple/Waze/ OSM/Bing, and "from A to B" directions requests.
Basic use:
u := mapsurl.Get("35.95277, 5.53753")
r := mapsurl.Resolve("from Setif to Algiers", mapsurl.WithMode("driving"))
The detection pipeline is an ordered registry; add your own types with Register without touching the core.
Index ¶
- func BuildCoords(lat, lng float64, o Options) string
- func BuildDirections(destination, origin string, o Options) string
- func BuildSearch(query string, o Options) string
- func CoordsFromURL(raw string) (lat, lng float64, ok bool)
- func ExtractURL(text string) (string, bool)
- func Get(text string, opts ...Option) string
- func IsGoogleLink(raw string) bool
- func IsMapLink(u string) bool
- func Normalize(text string) string
- func ParseCoordinates(text string) (lat, lng float64, ok bool)
- func ParsePlusCode(text string) (code, locality string, ok bool)
- func Register(kind Kind, priority int, fn Handler)
- type Handler
- type Kind
- type Option
- type Options
- type Resolution
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildCoords ¶
BuildCoords renders a coordinate URL, using the legacy ?q=&z= form when a zoom level is requested (the api=1 search form has no zoom parameter).
func BuildDirections ¶
BuildDirections renders a turn-by-turn URL; origin may be empty.
func BuildSearch ¶
BuildSearch renders a place-search URL for free text.
func CoordsFromURL ¶
CoordsFromURL recovers a coordinate pair from a map link of any provider.
func ExtractURL ¶
ExtractURL pulls the first URL out of arbitrary text, adding a scheme when the user pasted a bare host.
func IsGoogleLink ¶
IsGoogleLink matches on label boundaries, so bing.com never matches g.co.
func Normalize ¶
Normalize folds digits, punctuation and whitespace so detection can rely on a single canonical shape. It is never used to build address queries.
func ParseCoordinates ¶
ParseCoordinates accepts decimal, DMS, degree-minute, hemisphere-suffixed, labeled and non-ASCII-digit coordinate pairs. ok is false when the text is not a coordinate pair or falls outside valid lat/lng ranges.
func ParsePlusCode ¶
ParsePlusCode validates an Open Location Code. Short codes (fewer than eight characters before the '+') are rejected unless a locality follows them.
Types ¶
type Handler ¶
type Handler func(raw, norm string, o Options) *Resolution
Handler inspects the raw and normalized input and returns a Resolution, or nil to pass the input down to the next handler.
Every handler takes the full Options even when it ignores them, because the signature is the extension point: a third-party handler registered through Register has to be able to honour zoom, language and region without the registry needing a second handler shape.
type Kind ¶
type Kind string
Kind is the detected category of an input string.
const ( // KindEmpty means the input held nothing once normalization was applied. KindEmpty Kind = "empty" // KindDirections means the input named both an origin and a destination. KindDirections Kind = "directions" // KindGeoURI means the input was an RFC 5870 geo: URI. KindGeoURI Kind = "geo_uri" // KindLink means the input was a URL that is handed on unchanged. KindLink Kind = "link" // KindMapLink means coordinates were recovered from a non-Google map link. KindMapLink Kind = "map_link" // KindPlusCode means the input was an Open Location Code. KindPlusCode Kind = "plus_code" // KindCoordinates means the input was a latitude/longitude pair. KindCoordinates Kind = "coordinates" // KindAddress means nothing more specific matched, so the text is searched. KindAddress Kind = "address" )
The categories the pipeline can report. The order below is the order the default handlers are tried in, so the more specific shapes win over the free-text fallback.
type Option ¶
type Option func(*Options)
Option applies a single setting.
func RewriteGoogleLinks ¶
func RewriteGoogleLinks() Option
RewriteGoogleLinks rebuilds Google links from their coordinates rather than passing them through, which is what a caller wants when the other options have to be applied to an already-Google URL.
func WithLanguage ¶
WithLanguage sets the hl= interface language.
func WithOptions ¶
WithOptions replaces the whole option set at once, for a caller that already holds a filled-in Options.
func WithOrigin ¶
WithOrigin forces a directions URL starting at s.
type Options ¶
type Options struct {
// Zoom is 1..21 and switches coordinates to the ?q=&z= form.
Zoom int
// Mode is driving, walking, bicycling or transit.
Mode string
// Origin forces a directions URL from that place.
Origin string
// Language becomes the hl= parameter.
Language string
// Region becomes the gl= parameter.
Region string
// RewriteGoogleLinks rebuilds Google links instead of passing them through.
RewriteGoogleLinks bool
}
Options tunes URL construction. The zero value is the sensible default: Google links pass through untouched and no extra parameters are added.
type Resolution ¶
type Resolution struct {
// Kind is the category the pipeline settled on.
Kind Kind
// URL is the Google Maps link to encode or open.
URL string
// Raw is the input exactly as it arrived.
Raw string
// Normalized is Raw after digit, punctuation and whitespace folding.
Normalized string
// Lat and Lng are nil when the input carried no coordinates.
Lat, Lng *float64
// Query is the text sent to Google, for the kinds that search.
Query string
// Confidence is 1 for an unambiguous shape and lower for a guess.
Confidence float64
// Notes explain a decision that is not obvious from Kind alone.
Notes []string
}
Resolution is the full outcome of resolving one input string.
func Resolve ¶
func Resolve(text string, opts ...Option) Resolution
Resolve runs the pipeline and returns the full outcome.
func (Resolution) HasCoords ¶
func (r Resolution) HasCoords() bool
HasCoords reports whether latitude and longitude were recovered.
func (Resolution) String ¶
func (r Resolution) String() string
String makes a Resolution usable anywhere the URL string is expected.
Source Files