routific

README

Routific

Go wrapper for Routific Engine API

Routific.com is a multi-stop route planning provider. This package provides functions to call Routific API as documented in the Routific Engine API documentation.

Specifically, the package provides wrappers for vehicle routing problem (VRP), pickup-and-delivery problem (PDP), long-running VRP, and long-running PDP.

Documentation

Overview

Package routific is a wrapper for [Routific Engine API]: https://docs.routific.com/reference/api-reference. The package implements the API calls for vehicle routing problem (VRP), pickup-and-delivery problem (PDP), long-running VRP, and long-running PDP.

The calls take a plan (visits, fleet, and options) and return a Schedule. Prerequisite: Routific API token.

Index

• type Destination
• type Location
• type Options
• type PDPlan
• type PickDropOrder
• type Schedule
  • func LongPDP(visits PDPlan, token string, interval uint16, maxRetry uint8) (Schedule, error)
  • func LongVRP(visits VRPlan, token string, interval uint16, maxRetry uint8) (Schedule, error)
  • func PDP(visits PDPlan, token string) (Schedule, error)
  • func VRP(visits VRPlan, token string) (Schedule, error)
• type Stop
• type Stops
• type TimeWindow
• type VRPlan
• type Vehicle
• type VehicleOvertime
• type Visit

Types

type Destination

type Destination struct {
	Location Location `json:"location"`
	Start    string   `json:"start,omitempty"`    // "hh:mm"
	End      string   `json:"end,omitempty"`      // "hh:mm"
	Duration uint8    `json:"duration,omitempty"` // minutes
}

Destination describes the location for pickup and dropoff.

type Location

type Location struct {
	ID        string  `json:"id,omitempty"`
	Name      string  `json:"name,omitempty"`
	Latitude  float32 `json:"lat,omitempty"`
	Longitude float32 `json:"lng,omitempty"`
}

Location describes the GPS coordinate of a location.

type Options

type Options struct {
	Traffic                 string  `json:"traffic,omitempty"`
	MinVisitsPerVehicle     uint8   `json:"min_visits_per_vehicle,omitempty"`
	Balance                 bool    `json:"balance,omitempty"`
	VisitBalanceCoefficient float32 `json:"visit_balance_coefficient,omitempty"`
	MinVehicles             bool    `json:"min_vehicles,omitempty"`
	ShortestDistance        bool    `json:"shortest_distance,omitempty"`
	SquashDurations         uint8   `json:"squash_durations,omitempty"`
	MaxVehicleOvertime      uint8   `json:"max_vehicle_overtime,omitempty"` // minutes
	MaxVisitLateness        uint8   `json:"max_visit_lateness,omitempty"`   // minutes
	Polylines               bool    `json:"polylines,omitempty"`
	AvoidTolls              bool    `json:"avoid_tolls,omitempty"`
	GeoCoder                string  `json:"geocoder,omitempty"`
}

Options tweak how the Routific Engine performs the optimisation. See [Input Options]: https://docs.routific.com/reference/options

type PDPlan

type PDPlan struct {
	Visits  map[string]PickDropOrder `json:"visits"`
	Fleet   map[string]Vehicle       `json:"fleet"`
	Options Options                  `json:"options,omitempty"`
}

PDPlan is the pickup and dropoff plan that we want Routific to solve / optimise.

type PickDropOrder

type PickDropOrder struct {
	Load    uint8       `json:"load,omitempty"`
	PickUp  Destination `json:"pickup,omitempty"`
	DropOff Destination `json:"dropoff,omitempty"`
	Type    []string    `json:"type,omitempty"`
}

PickDropOrder describes the targeted pickup and dropoff. See [Orders]: https://docs.routific.com/reference/defining-orders

type Schedule

type Schedule struct {
	Status        string            `json:"status"`
	TravelTime    float32           `json:"total_travel_time"` // minutes
	IdleTime      float32           `json:"total_idle_time"`   // minutes
	Fitness       uint8             `json:"fitness,omitempty"`
	NumUnserved   uint8             `json:"num_unserved"`
	Unserved      map[string]string `json:"unserved"`
	Solution      map[string]Stops  `json:"solution"`
	NumLateVisits uint8             `json:"num_late_visits,omitempty"`
	TotalLateness float32           `json:"total_visit_lateness,omitempty"` // minutes
	Overtime      VehicleOvertime   `json:"vehicle_overtime,omitempty"`
	TotalOvertime float32           `json:"total_overtime,omitempty"` // minutes
}

Schedule describes the Routific optimised schedule and route for the requested / input plan. See [Output]: https://docs.routific.com/reference/output

func LongPDP

func LongPDP(
	visits PDPlan,
	token string,
	interval uint16,
	maxRetry uint8,
) (Schedule, error)

LongPDP is a wrapper for Routific API for long-running pickup-and-delivery problem solver. See [Interval]: https://docs.routific.com/reference/vrp-long to determine how many seconds to wait according to the size of the input list. If Routific server is not finished in (interval x maxRetry) seconds, then the function returns empty schedule with error message ("Timed out").

func LongVRP

func LongVRP(
	visits VRPlan,
	token string,
	interval uint16,
	maxRetry uint8,
) (Schedule, error)

LongVRP is a wrapper for Routific API for long-running vehicle routing problem solver. See [Interval]: https://docs.routific.com/reference/vrp-long to determine how many seconds to wait according to the size of the input list. If Routific server is not finished in (interval x maxRetry) seconds, then the function returns empty schedule with error message ("Timed out").

func PDP

func PDP(visits PDPlan, token string) (Schedule, error)

PDP is a wrapper for Routific API for pickup-and-delivery problem solver.

func VRP

func VRP(visits VRPlan, token string) (Schedule, error)

VRP is a wrapper for Routific API for vehicle routing problem solver.

type Stop

type Stop struct {
	ID          string  `json:"location_id,omitempty"`
	Name        string  `json:"location_name,omitempty"`
	ArrivalTime string  `json:"arrival_time,omitempty"` // "hh:mm"
	FinishTime  string  `json:"finish_time,omitempty"`  // "hh:mm"
	Type        string  `json:"type,omitempty"`
	Late        bool    `json:"too_late,omitempty"`
	LateBy      float32 `json:"late_by,omitempty"`
}

Stop defines the stop during the route for pickup or dropoff.

type Stops

type Stops []Stop

Stops defines the order of stops.

type TimeWindow

type TimeWindow struct {
	Start string `json:"start,omitempty"` // "hh:mm"
	End   string `json:"end,omitempty"`   // "hh:mm"
}

TimeWindow defines the time window when a location can be visited.

type VRPlan

type VRPlan struct {
	Visits  map[string]Visit   `json:"visits"`
	Fleet   map[string]Vehicle `json:"fleet"`
	Options Options            `json:"options,omitempty"`
}

VRPlan is the vehicle routing plan that we want Routific to solve / optimise.

type Vehicle

type Vehicle struct {
	StartLocation Location    `json:"start_location,omitempty"`
	EndLocation   Location    `json:"end_location,omitempty"`
	ShiftStart    string      `json:"shift_start,omitempty"` // "hh:mm"
	ShiftEnd      string      `json:"shift_end,omitempty"`   // "hh:mm"
	Capacity      uint8       `json:"capacity,omitempty"`
	Type          string      `json:"type,omitempty"`
	Speed         string      `json:"speed,omitempty"`
	StrictStart   bool        `json:"strict_start,omitempty"`
	MinVisits     uint8       `json:"min_visits,omitempty"`
	Breaks        interface{} `json:"breaks,omitempty"`
}

Vehicle describes the vehicle or driver in the fleet. See [Fleet]: https://docs.routific.com/reference/fleet

type VehicleOvertime

type VehicleOvertime map[string]float32

VehicleOvertime describes how many minutes each vehicle may have overtime in the schedule.

type Visit

type Visit struct {
	Location    Location     `json:"location,omitempty"`
	Start       string       `json:"start,omitempty"`    // "hh:mm"
	End         string       `json:"end,omitempty"`      // "hh:mm"
	Duration    uint8        `json:"duration,omitempty"` // minutes
	Load        interface{}  `json:"load,omitempty"`
	Type        string       `json:"type,omitempty"`
	Priority    string       `json:"priority,omitempty"`
	TimeWindows []TimeWindow `json:"time_windows,omitempty"`
	Notes       string       `json:"notes,omitempty"`
	CustomNotes interface{}  `json:"customNotes,omitempty"`
}

Visit describes the targeted visit. See [Visits]: https://docs.routific.com/reference/input