routific 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d2e7ffe5c2bb636a3ab3c1e594516b763d2e8197
+  data.tar.gz: be71b166f79ade2947066ab085952980b04b5a5d
+SHA512:
+  metadata.gz: ef023e2e3aca0209ded96748d90bc1cc158f05d819a057ad16a4d71fde24c9a113e4ee084ab388c4bcdc51bec5f51553dde2d9a1bff7bdabc0b604fe68b62caa
+  data.tar.gz: 007e6e6b7a0b5cbb8873aa25257835425f7ae0822d9afaa90a66f6cdac2f96341a9c0a3ccc366cddd57219c04a08029fbb3466059586623343ec55e455f50cd2

data/README.md

@@ -0,0 +1,150 @@
+Routific Ruby Gem
+=================
+
+This Ruby Gem assists users to easily access the [Routific API][1], which is a practical and scalable solution to the Vehicle Routing Problem.
+
+Logistics companies struggle with this challenge every day; most of them are still manually scheduling their fleet with a team of dispatchers.
+
+Routific can automate this process, and optimize it. The savings are tremendous: less fuel, and fewer vehicles, drivers and dispatchers.
+
+In the U.S., 1/8th of all fuel is consumed by trucks - that's 50 billion gallons a year. Our optimization algorithms will reduce that number by 20%!
+
+  [1]: https://routific.com
+
+Installing
+----------
+
+> gem install routific
+
+Usage
+-----
+Remember to require it before using it
+
+> require 'routific'
+
+The following instance methods are available:
+
+ - Sets a location with the specified ID and parameters
+
+    Required arguments in params:
+  
+     - lat: Latitude of this location
+     - lng: Longitude of this location
+
+    Optional arguments in params:
+     - name: Name of this location
+
+   > routific.setLocation( id, params )
+
+ - Sets a visit for the specified location using the specified parameters
+
+    Optional arguments in params:
+     - 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
+
+   > routific.setVisit( id, [params] )
+
+ - Sets a vehicle with the specified ID and parameters
+ 
+    Required arguments in params:
+     - start_location: ID of start location for this vehicle
+
+    Optional arguments in params:
+     - end_location: ID of end location for this vehicle
+     - 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
+
+   > routific.setVehicle( id, params )
+
+ - Returns the route using the previously provided network, visits and
+   fleet information
+   > routific.getRoute()
+
+The following class methods are available:
+
+ - Sets the default access token to use
+   > Routific.setToken( token )
+
+ - Returns the route using the specified access token, network, visits and fleet information
+   > Routific.getRoute( id, [params] )
+
+Both getRoute functions return the Route object, which has the following methods:
+
+ - status: A sanity check, will always be success when the HTTP code is 200
+ - fitness: Total travel-time, representing the fitness score of the solution (less is better)
+ - unserved: List of visits that could not be scheduled. 
+ - vehicleRoutes: The optimized schedule
+
+Examples
+--------
+Example 1:
+
+    require 'routific'
+    
+    routific = Routific.new(--API_KEY--)
+    routific.setLocation("order_1", {
+      "name" => "6800 Cambie",
+      "lat" => 49.227107,
+      "lng" => -123.1163085,
+    })
+    
+    routific.setLocation("depot", {
+      "name" => "800 Kingsway",
+      "lat" => 49.2553636,
+      "lng" => -123.0873365,
+    })
+    
+    routific.setVisit("order_1", {
+      "start" => "9:00",
+      "end" => "12:00",
+      "duration" => 10,
+    })
+    
+    routific.setVehicle("vehicle_1", {
+      "start_location" => "depot",
+      "end_location" => "depot",
+      "shift_start" => "8:00",
+      "shift_end" => "12:00",
+    })
+    
+Example 2:
+
+    require 'routific'
+    
+    Routific.setToken(--API_KEY--)
+    network = {
+        "order_1" => {
+          "name" => "6800 Cambie",
+          "lat" => 49.227107,
+          "lng" => -123.1163085
+        },
+        "depot" => {
+          "name" => "800 Kingsway",
+          "lat" => 49.2553636,
+          "lng" => -123.0873365
+        }
+    }
+    visits = {
+        "order_1" => {
+          "start" => "9:00",
+          "end" => "12:00",
+          "duration" => 10
+        }
+    }
+    fleet = {
+        "vehicle_1" => {
+          "start-location" => "depot",
+          "end-location" => "depot",
+          "shift-start" => "8:00",
+          "shift-end" => "12:00"
+        }
+    }
+    @data = {
+        network: network,
+        visits: visits,
+        fleet: fleet
+    }
+    Routific.getRoute(@data)

data/lib/routific.rb

@@ -0,0 +1,88 @@
+require 'rest-client'
+require 'json'
+
+require_relative './routific/location'
+require_relative './routific/visit'
+require_relative './routific/vehicle'
+require_relative './routific/route'
+require_relative './routific/way_point'
+
+# Main class of this gem
+class Routific
+  attr_reader :token, :network, :visits, :fleet
+
+  # Constructor
+  # token: Access token for Routific API
+  def initialize(token)
+    @token = token
+    @network = {}
+    @visits = {}
+    @fleet = {}
+  end
+
+  # Sets a location with the specified ID and parameters
+  # id: location ID
+  # params: parameters for this location
+  def setLocation(id, params)
+    network[id] = Location.new(params)
+  end
+
+  # Sets a visit for the specified location using the specified parameters
+  # id: ID of location to visit
+  # params: parameters for this visit
+  def setVisit(id, params={})
+    visits[id] = Visit.new(params)
+  end
+
+  # Sets a vehicle with the specified ID and parameters
+  # id: vehicle ID
+  # params: parameters for this vehicle
+  def setVehicle(id, params)
+    fleet[id] = Vehicle.new(params)
+  end
+
+  # Returns the route using the previously provided network, visits and fleet information
+  def getRoute
+    data = {
+      network: network,
+      visits: visits,
+      fleet: fleet
+    }
+
+    Routific.getRoute(data, token)
+  end
+
+  class << self
+    # Sets the default access token to use
+    def setToken(token)
+      @@token = token
+    end
+
+    def token
+      @@token
+    end
+
+    # Returns the route using the specified access token, network, visits and fleet information
+    # If no access token is provided, the default access token previously set is used
+    # If the default access token either is nil or has not been set, an ArgumentError is raised
+    def getRoute(data, token = @@token)
+      if token.nil?
+        raise ArgumentError, "access token must be set"
+      end
+
+      # Sends HTTP request to Routific API server
+      response = RestClient.post('https://routific.com/api/vrp', 
+        data.to_json,
+        'Authorization' => "bearer #{token}",
+        content_type: :json,
+        accept: :json
+        )
+
+      # Parse the HTTP request response to JSON
+      jsonResponse = JSON.parse(response)
+
+      # Parse the JSON representation into a Route object
+      Route.parse(jsonResponse)
+    end
+  end
+end

data/lib/routific/location.rb

@@ -0,0 +1,41 @@
+# This class represents a location in the network
+class Location
+  attr_accessor :name, :lat, :lng
+
+  # Constructor
+  #
+  # Required arguments in params:
+  # lat: Latitude of this location
+  # lng: Longitude of this location
+  #
+  # Optional arguments in params:
+  # name: Name of this location
+  def initialize(params)
+    # Validates the parameters provided
+    validate(params)
+
+    @lat = params["lat"]
+    @lng = params["lng"]
+    @name = params["name"]
+  end
+
+  # Returns the JSON representation of this object
+  def to_json(options = nil)
+    jsonData = {}
+    jsonData["name"] = self.name if self.name
+    jsonData["lat"] = self.lat
+    jsonData["lng"] = self.lng
+
+    jsonData.to_json
+  end
+
+  private
+  # Validates the parameters being provided
+  # Raises an ArgumentError if any of the required parameters is not provided.
+  # Required parameters are: latitude and longitude
+  def validate(params)
+    if(params["lat"].nil? || params["lng"].nil?)
+      raise ArgumentError, "'lat' and 'lng' parameters must be provided"
+    end
+  end
+end

data/lib/routific/route.rb

@@ -0,0 +1,49 @@
+# This class represents the resulting route returned by the Routific API
+class Route
+  attr_reader :status, :fitness, :unserved, :vehicleRoutes
+
+  # Constructor
+  def initialize(status, fitness, unserved)
+    @status = status
+    @fitness = fitness
+    @unserved = unserved
+    @vehicleRoutes = Hash.new()
+  end
+
+  # Adds a new way point for the specified vehicle
+  def addWayPoint(vehicle_name, way_point)
+    if @vehicleRoutes[vehicle_name].nil?
+      # No previous way point was added for the specified vehicle, so create a new array
+      @vehicleRoutes[vehicle_name] = []
+    end
+    # Adds the provided way point for the specified vehicle
+    @vehicleRoutes[vehicle_name] << way_point
+  end
+
+  class << self
+    # Parse the JSON representation of a route, and return it as a Route object
+    def parse(routeJson)
+      status = routeJson["status"]
+      fitness = routeJson["fitness"]
+      unserved = routeJson["unserved"]
+      route = Route.new(status, fitness, unserved)
+
+      # Get way points for each vehicles
+      routeJson["solution"].each do |vehicle_name, way_points|
+        # Get all way points for this vehicle
+        way_points.each do |waypoint_info|
+          # Get all information for this way point
+          location_id = waypoint_info["location_id"]
+          location_name = waypoint_info["location_name"]
+          arrival_time = waypoint_info["arrival_time"]
+          finish_time = waypoint_info["finish_time"]
+          way_point = WayPoint.new(location_id, location_name, arrival_time, finish_time)
+          route.addWayPoint(vehicle_name, way_point)
+        end
+      end
+
+      # Return the resulting Route object
+      route
+    end
+  end
+end

data/lib/routific/vehicle.rb

@@ -0,0 +1,47 @@
+# This class represents a vehicle in the fleet
+class Vehicle
+  attr_accessor :start_location, :end_location, :shift_start, :shift_end, :capacity
+
+  # Constructor
+  #
+  # Required arguments in params:
+  # start_location: ID of start location for this vehicle
+  #
+  # Optional arguments in params:
+  # end_location: ID of end location for this vehicle
+  # 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
+  def initialize(params)
+    # Validates the provided parameters
+    validate(params)
+
+    @start_location = params["start_location"]
+    @end_location = params["end_location"]
+    @shift_start = params["shift_start"]
+    @shift_end = params["shift_end"]
+    @capacity = params["capacity"]
+  end
+
+  # Returns the JSON representation of this object
+  def to_json(options = nil)
+    jsonData = {}
+    jsonData["start-location"] = self.start_location
+    jsonData["end-location"] = self.end_location if self.end_location
+    jsonData["shift-start"] = self.shift_start if self.shift_start
+    jsonData["shift-end"] = self.shift_end if self.shift_end
+    jsonData["capacity"] = self.capacity if self.capacity
+
+    jsonData.to_json
+  end
+
+  private
+  # Validates the parameters being provided
+  # Raises an ArgumentError if any of the required parameters is not provided.
+  # Required parameter is: start_location
+  def validate(params)
+    if(params["start_location"].nil?)
+      raise ArgumentError, "'start_location' parameter must be provided"
+    end
+  end
+end

data/lib/routific/visit.rb

@@ -0,0 +1,29 @@
+# This class represents a location to be visited
+class Visit
+  attr_reader :start, :end, :duration, :demand
+
+  # Constructor
+  #
+  # Optional arguments in params:
+  # 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
+  def initialize(params = {})
+    @start = params["start"]
+    @end = params["end"]
+    @duration = params["duration"]
+    @demand = params["demand"]
+  end
+
+  # Returns the JSON representation of this object
+  def to_json(options = nil)
+    jsonData = {}
+    jsonData["start"] = self.start if self.start
+    jsonData["end"] = self.end if self.end
+    jsonData["duration"] = self.duration if self.duration
+    jsonData["demand"] = self.demand if self.demand
+
+    jsonData.to_json
+  end
+end

data/lib/routific/way_point.rb

@@ -0,0 +1,12 @@
+# This class represents a location to visit in the route
+class WayPoint
+  attr_reader :location_id, :location_name, :arrival_time, :finish_time
+
+  # Constructor
+  def initialize(location_id, location_name, arrival_time, finish_time)
+    @location_id = location_id
+    @location_name = location_name
+    @arrival_time = arrival_time
+    @finish_time = finish_time
+  end
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: routific
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Marc Kuo
+- Andre Soesilo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: pry-debugger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: Gem to use Routific API
+email: asoesilo@live.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- "./lib/routific.rb"
+- "./lib/routific/location.rb"
+- "./lib/routific/route.rb"
+- "./lib/routific/vehicle.rb"
+- "./lib/routific/visit.rb"
+- "./lib/routific/way_point.rb"
+- README.md
+homepage: https://routific.com/
+licenses:
+- MIT
+metadata:
+  source_code: https://github.com/asoesilo/routific-gem
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: routific API
+test_files: []