applemaps

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 5, 2024 License: BSD-3-Clause Imports: 11 Imported by: 0

README

A Go client library for the Apple Maps Server API

header_img

To learn about the Apple Maps Server API and all its methods, check the official documentation here: https://developer.apple.com/documentation/applemapsserverapi

Installation

go get github.com/jweckschmied/applemaps-go

Getting Started

An Apple Developer account is required to use the Apple Maps Server API. If you have a Developer Account, you can learn more about how to get a Maps Identifier, Private Key and Auth Token in the Apple MapKit JS Documentation: https://developer.apple.com/documentation/mapkitjs/creating_a_maps_identifier_and_a_private_key

The only information you need to provide to use this package is the JWT Auth Token.

Generating the JWT

Since the JWT will expire at some point, it needs to be regenerated on a regular basis. You can do this however you like, for example using one of the available golang JWT packages.

Details on the JWT creation can be found here: https://developer.apple.com/documentation/mapkitjs/creating_and_using_tokens_with_mapkit_js

Use the SetAuthToken() method to set a new token for an already existing client.

Usage Example

import (
    "context"
    "net/http"
	
    "github.com/jweckschmied/applemaps-go"
)

func main() {
    ctx := context.Background()
    httpClient := http.DefaultClient
    client := applemaps.NewAppleMaps(httpClient, "<your-auth-token>")
    result, err := client.Search(
        ctx,
        "Tour Eiffel",
        applemaps.WithLanguage(language.French),
        applemaps.WithResultTypeFilter("Poi"),
        applemaps.WithUserLocation(applemaps.NewLocation(48.858093, 2.294694)),
    )
}

Request Options

The following options are available for the different methods provided by the API. Please check the docs for details on which parameters can be used for each API method.

WithExcludePoiCategories
WithIncludePoiCategories
WithLimitToCountries
WithResultTypeFilter
WithLanguage
WithArrivalDate
WithDepartureDate
WithRequestsAlternateRoutes
WithTransportType
WithSearchLocation
WithAvoid
WithSearchRegion
WithUserLocation

For example, if you wanted to set the userLocation, along with includePoiCategories=Bank,Bakery, the function call should look like this:

client.Search(
    "Search Query",
    applemaps.WithUserLocation(applemaps.NewLocation(51.08097475066115, 13.76077443357895)),
    applemaps.WithIncludePoiCategories(applemaps.Bank, applemaps.Bakery),
)

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AccessToken 

type AccessToken struct {
	Token      string `json:"accessToken"`
	Expiration int    `json:"expiresInSeconds"`
}

type AutocompleteResult 

type AutocompleteResult struct {
	CompletionUrl     string            `json:"completionUrl"`
	DisplayLines      []string          `json:"displayLines"`
	Location          Location          `json:"location"`
	StructuredAddress StructuredAddress `json:"structuredAddress"`
}

type Avoid 

type Avoid string
const Tolls Avoid = "Tolls"

func (Avoid) String 

func (a Avoid) String() string

type Category 

type Category string
const (
	// Airport an airport
	Airport Category = "Airport"
	// AirportGate a specific gate at an airport
	AirportGate Category = "AirportGate"
	// AirportTerminal a specific named terminal at an airport
	AirportTerminal Category = "AirportTerminal"
	// AmusementPark An amusement parka
	AmusementPark Category = "AmusementPark"
	// ATM an Automated Teller Machine
	ATM Category = "ATM"
	// Aquarium an Aquarium
	Aquarium Category = "Aquarium"
	// Bakery a bakery
	Bakery Category = "Bakery"
	// Bank a bank
	Bank Category = "Bank"
	// Beach a beach
	Beach Category = "Beach"
	// Brewery a brewery
	Brewery Category = "Brewery"
	// Cafe a Cafe
	Cafe Category = "Cafe"
	// Campground a campground
	Campground Category = "Campground"
	// CarRental a Car Rental Location
	CarRental Category = "CarRental"
	// EVCharger an Electric Vehicle (EV) Charger
	EVCharger Category = "EVCharger"
	// FireStation a fire station
	FireStation Category = "FireStation"
	// FitnessCenter a fitness center
	FitnessCenter Category = "FitnessCenter"
	// FoodMarket a food market
	FoodMarket Category = "FoodMarket"
	// GasStation a gas station
	GasStation Category = "GasStation"
	// Hospital a hospital
	Hospital Category = "Hospital"
	// Hotel a hotel
	Hotel Category = "Hotel"
	// Laundry a laundry
	Laundry Category = "Laundry"
	// Library a library
	Library Category = "Library"
	// Marina a marina
	Marina Category = "Marina"
	// MovieTheater a movie theater
	MovieTheater Category = "MovieTheater"
	// Museum a museum
	Museum Category = "Museum"
	// NationalPark a national park
	NationalPark Category = "NationalPark"
	// Nightlife a nightlife venue
	Nightlife Category = "Nightlife"
	// Park a park
	Park Category = "Park"
	// Parking a parking location for an automobile
	Parking Category = "Parking"
	// Pharmacy a pharmacy
	Pharmacy Category = "Pharmacy"
	// Playground a playground
	Playground Category = "Playground"
	// Police a police station
	Police Category = "Police"
	// PostOffice a post office
	PostOffice Category = "PostOffice"
	// PublicTransport a public transportation station
	PublicTransport Category = "PublicTransport"
	// ReligiousSite a religious site
	ReligiousSite Category = "ReligiousSite"
	// Restaurant a restaurant
	Restaurant Category = "Restaurant"
	// Restroom a restroom
	Restroom Category = "Restroom"
	// School a school
	School Category = "School"
	// Stadium a stadium
	Stadium Category = "Stadium"
	// Store a store
	Store Category = "Store"
	// Theater a theater
	Theater Category = "Theater"
	// University a university
	University Category = "University"
	// Winery a winery
	Winery Category = "Winery"
	// Zoo a zoo
	Zoo Category = "Zoo"
)

func (Category) String 

func (c Category) String() string

type Client 

type Client interface {
	Geocode(ctx context.Context, query string, opts ...RequestOption) ([]Place, error)
	ReverseGeocode(ctx context.Context, location Location, opts ...RequestOption) ([]Place, error)

	Search(ctx context.Context, query string, opts ...RequestOption) (*SearchResponse, error)
	SearchAutocomplete(ctx context.Context, query string, opts ...RequestOption) (*SearchAutocompleteResult, error)

	Directions(ctx context.Context, origin, destination string, opts ...RequestOption) (*DirectionsResponse, error)
	Etas(ctx context.Context, origin Location, destinations []Location, opts ...RequestOption) (*EtaResponse, error)

	SetAuthToken(authToken string)
}

func NewAppleMaps 

func NewAppleMaps(httpClient *http.Client, authToken string, options ...ClientOption) Client

NewAppleMaps returns a new Apple Maps Server API Client given a http client and a JWT Auth Token for the API. If you need to specify a custom API URL, use WithCustomURL() as an option.

type ClientOption 

type ClientOption func(c *client)

func WithCustomURL 

func WithCustomURL(baseURL string) ClientOption

WithCustomURL returns a functional ClientOption used to set a custom base URL when creating a new Apple Maps API Client using NewAppleMaps().

type DirectionsResponse 

type DirectionsResponse struct {
	Destination Place        `json:"destination"`
	Origin      Place        `json:"origin"`
	Routes      []Route      `json:"routes"`
	StepPaths   [][]Location `json:"stepPaths"`
	Steps       []Step       `json:"steps"`
}

type Eta 

type Eta struct {
	Destination               Location `json:"destination"`
	DistanceMeters            int      `json:"distanceMeters"`
	ExpectedTravelTimeSeconds int      `json:"expectedTravelTimeSeconds"`
	StaticTravelTimeSeconds   int      `json:"staticTravelTimeSeconds"`
	TransportType             string   `json:"transportType"`
}

type EtaResponse 

type EtaResponse struct {
	Etas []Eta `json:"etas"`
}

type Location 

type Location struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

func NewLocation 

func NewLocation(lat, lng float64) Location

NewLocation creates a new coordinate object

func (Location) String 

func (l Location) String() string

type MapRegion 

type MapRegion struct {
	NorthLatitude float64 `json:"northLatitude"`
	EastLongitude float64 `json:"eastLongitude"`
	SouthLatitude float64 `json:"southLatitude"`
	WestLongitude float64 `json:"westLongitude"`
}

func NewRegion 

func NewRegion(northLat, eastLon, southLat, westLon float64) MapRegion

NewRegion creates a new map region object

func (MapRegion) String 

func (r MapRegion) String() string

type Place 

type Place struct {
	Country               string            `json:"country"`
	CountryCode           string            `json:"countryCode"`
	DisplayMapRegion      MapRegion         `json:"displayMapRegion"`
	FormattedAddressLines []string          `json:"formattedAddressLines"`
	Name                  string            `json:"name"`
	Coordinate            Location          `json:"coordinate"`
	StructuredAddress     StructuredAddress `json:"structuredAddress"`
}

type RequestOption 

type RequestOption func(v url.Values)

func WithArrivalDate 

func WithArrivalDate(arrival time.Time) RequestOption

WithArrivalDate provides an option to add the date and time to arrive at the destination. You can specify only arrivalDate or departureDate. If you don’t specify either option, the departureDate defaults to now, which the server interprets as the current time.

func WithAvoid 

func WithAvoid(avoid ...Avoid) RequestOption

WithAvoid provides an option to add a slice of the features to avoid when calculating direction routes. For example, avoid=Tolls. See Avoid type for a complete list of possible values.

func WithDepartureDate 

func WithDepartureDate(departure time.Time) RequestOption

WithDepartureDate provides an option to add the date and time to depart from the origin. You can only specify arrivalDate or departureDate. If you don’t specify either option, the departureDate defaults to now, which the server interprets as the current time.

func WithExcludePoiCategories 

func WithExcludePoiCategories(categories ...Category) RequestOption

WithExcludePoiCategories provides an option to add a slice of strings that describes the points of interest to exclude from the search results. For example, excludePoiCategories=Restaurant,Cafe. See Category type for a complete list of possible values.

func WithIncludePoiCategories 

func WithIncludePoiCategories(categories ...Category) RequestOption

WithIncludePoiCategories provides an option to add a slice of Categories that describes the points of interest to include in the search results. For example, includePoiCategories=Restaurant,Cafe. See Category type for a complete list of possible values.

func WithLanguage 

func WithLanguage(lang language.Tag) RequestOption

WithLanguage provides an option to add the language the server should use when returning the response, specified using a BCP 47 language code. For example, for English use lang=en-US. Defaults to en-US.

func WithLimitToCountries 

func WithLimitToCountries(countries ...string) RequestOption

WithLimitToCountries provides an option to add a slice of ISO ALPHA-2 codes of the countries to limit the results to. For example, limitToCountries=US,CA limits the search to the United States and Canada. If you specify two or more countries, the results reflect the best available results for some or all of the countries rather than everything related to the query for those countries.

func WithRequestsAlternateRoutes 

func WithRequestsAlternateRoutes() RequestOption

WithRequestsAlternateRoutes provides an option for the server to return additional routes, when available. For example, requestsAlternateRoutes=true. Default: false

func WithResultTypeFilter 

func WithResultTypeFilter(filters ...string) RequestOption

WithResultTypeFilter provides an option to add a slice of strings that describes the kind of result types to include in the response. For example, resultTypeFilter=Poi. Possible Values: Poi, Address

func WithSearchLocation 

func WithSearchLocation(location Location) RequestOption

WithSearchLocation provides an option to set a hint for the query input for origin or destination. If you don’t provide a searchLocation, the server uses userLocation and searchLocation as fallback hints.

func WithSearchRegion 

func WithSearchRegion(region MapRegion) RequestOption

WithSearchRegion provides an option to set a region the app defines as a hint for the query input for origin or destination. If you don’t provide a searchLocation, the server uses userLocation and searchRegion as fallback hints.

func WithTransportType 

func WithTransportType(transportType string) RequestOption

WithTransportType provides an option to set the mode of transportation the server returns directions for. Default: Automobile Possible Values: Automobile, Walking

func WithUserLocation 

func WithUserLocation(location Location) RequestOption

WithUserLocation provides an option to set the location of the user. If you don’t provide a searchLocation, the server uses userLocation and searchRegion as fallback hints.

type Route 

type Route struct {
	DistanceMeters  int    `json:"distanceMeters"`
	DurationSeconds int    `json:"durationSeconds"`
	HasTolls        bool   `json:"hasTolls"`
	Name            string `json:"name"`
	StepIndexes     []int  `json:"stepIndexes"`
	TransportType   string `json:"transportType"`
}

type SearchAutocompleteResult 

type SearchAutocompleteResult struct {
	Results []AutocompleteResult `json:"results"`
}

type SearchResponse 

type SearchResponse struct {
	DisplayMapRegion MapRegion `json:"displayMapRegion"`
	Results          []Place   `json:"results"`
}

type Step 

type Step struct {
	DistanceMeters  int    `json:"distanceMeters"`
	DurationSeconds int    `json:"durationSeconds"`
	Instructions    string `json:"instructions"`
	StepPathIndex   int    `json:"stepPathIndex"`
	TransportType   string `json:"transportType"`
}

type StructuredAddress 

type StructuredAddress struct {
	AdministrativeArea     string   `json:"administrativeArea"`
	AdministrativeAreaCode string   `json:"administrativeAreaCode"`
	AreasOfInterest        []string `json:"areasOfInterest"`
	DependentLocalities    []string `json:"dependentLocalities"`
	FullThoroughfare       string   `json:"fullThoroughfare"`
	Locality               string   `json:"locality"`
	PostCode               string   `json:"postCode"`
	SubLocality            string   `json:"subLocality"`
	// SubThoroughfare The short code for the state or area.
	SubThoroughfare string `json:"subThoroughfare"`
	// Thoroughfare The state or province of the place
	Thoroughfare string `json:"thoroughfare"`
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.