here

package module
v0.25.0-dev.2 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2023 License: Apache-2.0 Imports: 11 Imported by: 0

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BoundingBox 

type BoundingBox struct {
	North float64
	South float64
	East  float64
	West  float64
}

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.

Source Files

View all Source files

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.