Documentation ¶
Overview ¶
Package here provides a client for measuring distances and durations.
A HERE client requests distance and duration data using HERE Maps API. It makes requests to construct a matrix measure.
The client can construct a distance matrix, a duration matrix, or both.
Each of these functions will use a synchronous request flow if the number of points requested is below HERE's size limit for synchronous API calls - otherwise, an asynchronous flow will be used. The functions all take a context which can be used to cancel the request flow while it is in progress.
These measures implement route.ByIndex.
These matrix-generating functions can also take one or more options that allow you to configure the routes that will be included in the matrices.
Example ¶
How to create a `Client`, assuming the points are in the form `{longitude, latitude}`. Please note that this example does not define an output as it requires API authentication and is here for illustrative purposes only.
package main import ( "context" "fmt" "time" "github.com/nextmv-io/sdk/route" "github.com/nextmv-io/sdk/route/here" ) func main() { points := []route.Point{ {-74.028297, 4.875835}, {-74.046965, 4.872842}, {-74.041763, 4.885648}, } client := here.NewClient("<your-api-key>") // All of the matrix-constructing functions take a context as their first // parameter, which can be used to cancel a request cycle while it is in // progress. For example, it is a good general practice to use this context // to impose a timeout. ctx, cancel := context.WithTimeout(context.Background(), time.Second*5) defer cancel() // Distance and duration matrices can be constructed with the functions // provided in the package. These functions will use a synchronous request // flow if the number of points requested is below HERE's size limit for // synchronous API calls - otherwise, HERE's asynchronous flow will // automatically be used. dist, dur, err := client.DistanceDurationMatrices(ctx, points) if err != nil { panic(err) } _ = dist // We don't use the distance matrix in this example. // The matrix functions also take a variadic list of `MatrixOption`s that // configure how HERE will calculate the routes. For example, this code // constructs a DistanceMeasure with a specific departure time for a // bicycle: dist, err = client.DistanceMatrix( ctx, points, here.WithTransportMode(here.TransportModeBicycle), here.WithDepartureTime(time.Date(2021, 12, 10, 8, 30, 0, 0, time.Local)), ) if err != nil { panic(err) } _ = dist // We don't use the distance matrix in this example. // Or, you can configure a truck profile: dist, err = client.DistanceMatrix( ctx, points, here.WithTransportMode(here.TransportModeTruck), here.WithTruckProfile(here.Truck{ Type: here.TruckTypeTractor, TrailerCount: 2, ShippedHazardousGoods: []here.HazardousGood{here.Poison}, }), ) if err != nil { panic(err) } // Once the measures have been created, you may estimate the distances and // durations by calling the Cost function. for p1 := range points { for p2 := range points { fmt.Printf( "(%d, %d) = [%.2f, %.2f]\n", p1, p2, dist.Cost(p1, p2), dur.Cost(p1, p2), ) } } // This is the expected output. // (0, 0) = [0.00, 0.00] // (0, 1) = [6519.00, 791.00] // (0, 2) = [4884.00, 632.00] // (1, 0) = [5242.00, 580.00] // (1, 1) = [0.00, 0.00] // (1, 2) = [2270.00, 248.00] // (2, 0) = [3800.00, 493.00] // (2, 1) = [2270.00, 250.00] // (2, 2) = [0.00, 0.00] }
Output:
Index ¶
- type BoundingBox
- type Client
- type ClientOption
- type Feature
- type HazardousGood
- type MatrixOption
- func WithAvoidAreas(areas []BoundingBox) MatrixOption
- func WithAvoidFeatures(features []Feature) MatrixOption
- func WithDepartureTime(t time.Time) MatrixOption
- func WithScooterProfile(scooter Scooter) MatrixOption
- func WithTaxiProfile(taxi Taxi) MatrixOption
- func WithTransportMode(mode TransportMode) MatrixOption
- func WithTruckProfile(t Truck) MatrixOption
- type Scooter
- type Taxi
- type TransportMode
- type Truck
- type TruckType
- type TunnelCategory
- type WeightPerAxleGroup
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BoundingBox ¶
BoundingBox represents a region using four cooordinates corresponding to the furthest points in each of the cardinal directions within that region.
type Client ¶
type Client interface { // DistanceMatrix retrieves a HERE distance matrix. It uses the async HERE API // if there are more than 500 points given. DistanceMatrix( ctx context.Context, points []route.Point, opts ...MatrixOption, ) (route.ByIndex, error) // DurationMatrix retrieves a HERE duration matrix. It uses the async HERE API // if there are more than 500 points given. DurationMatrix( ctx context.Context, points []route.Point, opts ...MatrixOption, ) (route.ByIndex, error) // DistanceDurationMatrices retrieves a HERE distance and duration matrix. It // uses the async HERE API if there are more than 500 points given. DistanceDurationMatrices( ctx context.Context, points []route.Point, opts ...MatrixOption, ) (distances, durations route.ByIndex, err error) }
Client represents a HERE maps client. See official documentation for HERE topics, getting started.
func NewClient ¶
func NewClient(apiKey string, opts ...ClientOption) Client
NewClient returns a new OSRM Client.
type ClientOption ¶
type ClientOption func(*client)
ClientOption can pass options to be used with a HERE client.
func WithClientTransport ¶
func WithClientTransport(rt http.RoundTripper) ClientOption
WithClientTransport overwrites the RoundTripper used by the internal http.Client.
func WithDenyRedirectPolicy ¶
func WithDenyRedirectPolicy(hostnames ...string) ClientOption
WithDenyRedirectPolicy block redirected requests to specified hostnames. Matches hostname greedily e.g. google.com will match api.google.com, file.api.google.com, ...
type Feature ¶
type Feature string
Feature represents a geographical feature.
const CarShuttleTrain Feature = "carShuttleTrain"
CarShuttleTrain designates a train that can transport cars.
const ControlledAccessHighway Feature = "controlledAccessHighway"
ControlledAccessHighway designates a controlled access highway.
const DifficultTurns Feature = "difficultTurns"
DifficultTurns represents u-turns, difficult turns, and sharp turns.
const DirtRoad Feature = "dirtRoad"
DirtRoad designates a dirt road.
const Ferry Feature = "ferry"
Ferry designates a ferry route.
const SeasonalClosure Feature = "seasonalClosure"
SeasonalClosure designates a route that is closed for the season.
const TollRoad Feature = "tollRoad"
TollRoad designates a toll road feature.
const Tunnel Feature = "tunnel"
Tunnel designates a tunnel.
const UTurns Feature = "uTurns"
UTurns designates u-turns.
type HazardousGood ¶
type HazardousGood string
HazardousGood indicates a hazardous good that trucks can transport.
const Combustible HazardousGood = "combustible"
Combustible designates combustible materials.
const Corrosive HazardousGood = "corrosive"
Corrosive indicates corrosive materials.
const Explosive HazardousGood = "explosive"
Explosive represents explosive materials.
const Flammable HazardousGood = "flammable"
Flammable designates flammable materials.
const Gas HazardousGood = "gas"
Gas designates gas.
const HarmfulToWater HazardousGood = "harmfulToWater"
HarmfulToWater indicates materials that are harmful to water.
const Organic HazardousGood = "organic"
Organic designates organical materials.
const OtherHazardousGood HazardousGood = "other"
OtherHazardousGood refers to other types of hazardous materials.
const Poison HazardousGood = "poison"
Poison designates poison.
const PoisonousInhalation HazardousGood = "poisonousInhalation"
PoisonousInhalation refers to materials that are poisonous to inhale.
const Radioactive HazardousGood = "radioactive"
Radioactive indicates radioactive materials.
type MatrixOption ¶
type MatrixOption func(req *matrixRequest)
MatrixOption is passed to functions on the Client that create matrices, configuring the HERE request the client will make.
func WithAvoidAreas ¶
func WithAvoidAreas(areas []BoundingBox) MatrixOption
WithAvoidAreas sets bounding boxes that will be avoided in the calculated routes.
func WithAvoidFeatures ¶
func WithAvoidFeatures(features []Feature) MatrixOption
WithAvoidFeatures sets features that will be avoided in the calculated routes.
func WithDepartureTime ¶
func WithDepartureTime(t time.Time) MatrixOption
WithDepartureTime sets departure time to be used in the request. This will take traffic data into account for the given time. If no departure time is given, "any" will be used in the request and no traffic data is included, see official documentation for HERE matrix routing, concepts traffic.
func WithScooterProfile ¶
func WithScooterProfile(scooter Scooter) MatrixOption
WithScooterProfile sets a Scooter profile on the request.
func WithTaxiProfile ¶
func WithTaxiProfile(taxi Taxi) MatrixOption
WithTaxiProfile sets a Taxi profile on the request.
func WithTransportMode ¶
func WithTransportMode(mode TransportMode) MatrixOption
WithTransportMode sets the transport mode for the request.
func WithTruckProfile ¶
func WithTruckProfile(t Truck) MatrixOption
WithTruckProfile sets a Truck profile on the matrix request. The following attributes are required by HERE: * TunnelCategory: if this is an empty string, the Client will automatically set it to TunnelCategoryNone * Type * AxleCount.
type Scooter ¶
type Scooter struct {
AllowHighway bool `json:"allowHighway"` //nolint:tagliatelle
}
Scooter captures routing parameters that can be set on scooters.
type Taxi ¶
type Taxi struct {
AllowDriveThroughTaxiRoads bool `json:"allowDriveThroughTaxiRoads"` //nolint:tagliatelle,lll
}
Taxi captures routing parameters that can be set on taxis.
type TransportMode ¶
type TransportMode string
TransportMode represents the type of vehicle that will be used for the calculated routes.
const TransportModeBicycle TransportMode = "bicycle"
TransportModeBicycle causes routes to be calculated for bicycle travel.
const TransportModeCar TransportMode = "car"
TransportModeCar causes routes to be calculated for car travel.
const TransportModePedestrian TransportMode = "pedestrian"
TransportModePedestrian causes routes to be calculated for pedestrian travel.
const TransportModeScooter TransportMode = "scooter"
TransportModeScooter causes routes to be calculated for scooter travel.
const TransportModeTaxi TransportMode = "taxi"
TransportModeTaxi causes routes to be calculated for taxi travel.
const TransportModeTruck TransportMode = "truck"
TransportModeTruck causes routes to be calculated for truck travel.
type Truck ¶
type Truck struct { ShippedHazardousGoods []HazardousGood `json:"shippedHazardousGoods,omitempty"` //nolint:tagliatelle,lll // in kilograms GrossWeight int32 `json:"grossWeight,omitempty"` //nolint:tagliatelle // in kilograms WeightPerAxle int32 `json:"weightPerAxle,omitempty"` //nolint:tagliatelle // in centimeters Height int32 `json:"height,omitempty"` // in centimeters Width int32 `json:"width,omitempty"` // in centimeters Length int32 `json:"length,omitempty"` TunnelCategory TunnelCategory `json:"tunnelCategory,omitempty"` //nolint:tagliatelle,lll AxleCount int32 `json:"axleCount,omitempty"` //nolint:tagliatelle,lll Type TruckType `json:"type,omitempty"` TrailerCount int32 `json:"trailerCount,omitempty"` //nolint:tagliatelle,lll WeightPerAxleGroup *WeightPerAxleGroup `json:"weightPerAxleGroup,omitempty"` //nolint:tagliatelle,lll }
Truck captures truck-specific routing parameters.
type TruckType ¶
type TruckType string
TruckType specifies the type of truck.
const TruckTypeStraight TruckType = "straight"
TruckTypeStraight refers to trucks with a permanently attached cargo area.
const TruckTypeTractor TruckType = "tractor"
TruckTypeTractor refers to vehicles that can tow one or more semi-trailers.
type TunnelCategory ¶
type TunnelCategory string
TunnelCategory is a tunnel category used to restrict the transport of certain goods.
const TunnelCategoryB TunnelCategory = "B"
TunnelCategoryB represents tunnels with B category restrictions.
const TunnelCategoryC TunnelCategory = "C"
TunnelCategoryC represents tunnels with C category restrictions.
const TunnelCategoryD TunnelCategory = "D"
TunnelCategoryD represents a tunnel with D category restrictions.
const TunnelCategoryE TunnelCategory = "E"
TunnelCategoryE represents a tunnel with E category restrictions.
const TunnelCategoryNone TunnelCategory = "None"
TunnelCategoryNone represents a tunnel with no category restrictions.
type WeightPerAxleGroup ¶
type WeightPerAxleGroup struct { Single int32 `json:"single"` Tandem int32 `json:"tandem"` Triple int32 `json:"triple"` }
WeightPerAxleGroup captures the weights of different axle groups.