Skip to content

Latest commit

 

History

History
184 lines (145 loc) · 5.62 KB

README.md

File metadata and controls

184 lines (145 loc) · 5.62 KB
Raw

Routific Ruby Gem

Build Status

This Ruby Gem assists users to easily access the Routific API, which is a practical and scalable solution to the Vehicle Routing Problem and Traveling Salesman Problem.

Please refer to the full documentation for a detailled documentation of the API.

Installing

gem install routific

Usage

Remember to require it and set your token before using it

require 'routific'
Routific.set_token("YOUR_API_KEY_HERE")
routific = Routific.new

routific.set_visit("order_1", {
  "start" => "9:00",
  "end" => "12:00",
  "duration" => 10,
  "location" => {
    "name" => "6800 Cambie",
    "lat" => 49.227107,
    "lng" => -123.1163085,
  }
})

routific.set_visit("order_2", {
  "start" => "9:00",
  "end" => "12:00",
  "duration" => 10,
  "location" => {
    "name"=> "3780 Arbutus",
    "lat"=> 49.2474624,
    "lng"=> -123.1532338
  }
})

routific.set_vehicle("vehicle_1", {
  "start_location" => {
    "name" => "800 Kingsway",
    "lat" => 49.2553636,
    "lng" => -123.0873365,
  },
  "end_location" => {
    "name" => "800 Kingsway",
    "lat" => 49.2553636,
    "lng" => -123.0873365,
  },
  "shift_start" => "8:00",
  "shift_end" => "12:00",
})

routific.set_options({
  "polylines" => true
})

route = routific.get_route()


puts route.status # => "success"
puts route.total_travel_time # => 29
puts route.polylines["vehicle_1"] # => s`i}|AbxswiFnn@gdBvG?vVf@jC?nZRb[f@j\z@nZRnZRj\f@nZz

vehicle_routes = route.vehicle_routes

v1_route = vehicle_routes["vehicle_1"]
puts v1_route.length # => 4 (start -> order_1 -> order_2 -> end)

v1_route.each do |w|
  puts "#{w.location_id}: #{w.arrival_time} ~ #{w.finish_time}"
end
# vehicle_1_start: 08:49 ~
# order_1: 09:00 ~ 09:10
# order_2: 09:18 ~ 09:28
# vehicle_1_end: 09:38 ~

Class methods

Routific.set_token( token ) sets the authentication token to use.

Instance methods

routific.set_visit( id, params )

Sets a visit with the specified id and parameters:

  • location (required): Object representing the location of the visit.
    • lat: Latitude of this location
    • lng: Longitude of this location
    • name: (optional) Name of the location
  • start: the earliest time for this visit. Default value is 00:00, if not specified.
  • end: the latest time for this visit. Default value is 23:59, if not specified.
  • duration: the length of this visit in minutes
  • demand: the capacity that this visit requires
  • priority: higher priority visits are more likely to be served
  • type: restrict the vehicle that can serve this visit
  • time_windows: specify different time-windows for serving the visit. It should be an array of hashes: [ { "start" => "08:00", "end" => "12:00" } ]

routific.set_vehicle( id, params )

Sets a vehicle with the specified ID and parameters:

  • start_location (required): Object representing the start location for this vehicle.
    • lat: Latitude of this location
    • lng: Longitude of this location
    • name: (optional) Name of the location
  • end_location: Object representing the end location for this vehicle.
    • lat: Latitude of this location
    • lng: Longitude of this location
    • name: (optional) Name of the location
  • shift_start: this vehicle's start shift time (e.g. '08:00'). Default value is 00:00, if not specified.
  • shift_end: this vehicle's end shift time (e.g. '17:00'). Default value is 23:59, if not specified.
  • capacity: the capacity that this vehicle can load
  • type: restrict the visit this vehicle can serve
  • speed: vehicle speed
  • min_visits: minimum number of visits that should be assigned to this vehicle
  • strict_start: force the departure time to be shift_start
  • breaks: specify breaks for the driver. It should be an array of hashes: [ { "id" => "lunch", "start" => "12:00", "end" => "12:30" } ]

routific.set_options( params )

Sets optional options onto the route requests. Optional arguments must be one of the following:

  • traffic
  • min_visits_per_vehicle
  • balance
  • min_vehicles
  • shortest_distance
  • squash_duration
  • max_vehicle_overtime
  • max_visit_lateness

routific.get_route()

Returns an optimized route using the previously provided visits, fleet and options. The request may timeout if the problem is too large.

It returns a route object with the following attributes:

  • status: A sanity check
  • unserved: List of visits that could not be scheduled.
  • vehicle_routes: The optimized schedule
  • other attributes that you can find in the full documentation

The vehicle_routes attribute is a hash mapping vehicle ID to the corresponding route, represented as an array of waypoints: { "vehicle_1" => [ way_point_1, way_point_2, way_point_3, way_point_4 ] }

The waypoint object has the following attributes:

  • location_id
  • arrival_time
  • finish_time
  • other attributes that you can find in the full documentation

routific.get_route_async()

For requests with 60 visits and more, it is recommended to make asynchronous call to the API.

job = routific.get_route_async()
puts job.status # => "pending"
sleep 5
job.fetch
puts job.status # => "finished"
route = job.route

It returns a job object with the following attibutes:

  • status: status of the task ('pending', 'processing', 'finished', 'error')
  • id: a unique identifier for the task
  • created_at, finished_at: creation and finish times
  • input: the data used for the request
  • route: a route object