Package: elasticroute
ElasticRoute for PythonWith effect from 02 January 2021, we will deprecate support for this client library and there will be no future updates. If you are currently using the client library, the integrations done based on it should still be able to work. Moving forward, we recommend the use of our API documentation (DashboardandRouting Engine) to build your integration.API for solving large scale travelling salesman/fleet routing problemsYou have a fleet of just 10 vehicles to serve 500 spots in the city. Some vehicles are only available in the day. Some stops can only be served at night. How would you solve this problem?You don't need to. Just throw us a list of stops, vehicles and depots and we will do the heavy lifting for you.Routing as a Service!PreambleWe offer two API's: The Dashboard API, for developers looking to integrate their existing system with ourElasticRoute Dashboard; and the Routing Engine API, for developers looking to solve the Vehicle Routing Problem in a headless environment. The Routing Engine API is only available by request, while the Dashboard API is generally available. Read morehere.Backwards-compatibility notice:Due to significant overhauls in the backend API, major version 2 of this library isnotcompatible with code written to work with version 1 of this library.Quick Start Guide (Dashboard API)Install with pip:pip install elasticrouteCreate an instance ofDashboardClient, passing your API key to the constructor. The API Key can be retrieved from the dashboard of theweb application).fromelasticroute.clientsimportDashboardClientdashboard=DashboardClient("YOUR_API_KEY_HERE")You can then programmatically create stops to appear on your Dashboard:fromelasticroute.dashboardimportStopstop=Stop()stop["name"]="Changi Airport"stop["address"]="80 Airport Boulevard (S)819642"dashboard.stops.create(stop)Data attributes of models in this library are accessed and modified using the index operator[]. You can get/set any attributes listed inthis page(underField Headers and Description) that are not marked asResultorReadonly. Keys passed to the index operatormustbe strings. Passing non-string keys or attempting to modify readonly attributes will trigger a warning.By default, this creates a stop on today's date. Change the date by passing thedatekeyword argument:dashboard.stops.create(stop,date="2019-01-01")Date strings must follow theYYYY-MM-DDformat.All CRUD operations are available for stops with the following method signatures:dashboard.stops.create(stop)dashboard.stops.retrieve(stop_name)dashboard.stops.update(stop)dashboard.stops.delete(stop)All methods accept thedatekeyword argument. Thecreatemethod throws an exception (elasticroute.errors.repository.ERServiceException) if a stop with an existing name already exists on the same day, while theretrieve,updateanddeletemethods will throw an exception if a stop with the given name does not exist on that day.CRUD operations are also available for Vehicles:fromelasticroute.dashboardimportVehiclevehicle=Vehicle()vehicle["name"]="Morning shift driver"vehicle["avail_from"]=900vehicle["avail_to"]=1200dashboard.vehicles.create(vehicle)dashboard.vehicles.retrieve(vehicle_name)dashboard.vehicles.update(vehicle)dashboard.vehicles.delete(vehicle)Like for stops, thecreatemethod throwselasticroute.errors.repository.ERServiceExceptionif a vehicle with the same name already exists on the same account, whileretrieve,update,deletemethods will throw an exception if a vehicle with the given name does not yet exist in the account.Unlike stops, vehicles are not bound by date, and are present across all dates.Both stops and vehicles accept a dictionary in their constructor that automatically sets their corresponding data attributes.The library helps you check for invalid values before requests are sent to the server. For instance, setting a vehicle'savail_todata attribute to2500will trigger aelasticroute.errors.validator.BadFieldErrorwhen performing any CRUD operations.Currently, the Dashboard API is unable to perform CRUD operations on depots. Since the details of depots are likely not going to be changed frequently, please configure (using the web application) all the depots that your team has before using this library to perform plans.Programmatically starting the planning processOnce you have created more than one stop for the day (and created a starting depot via the web application), you can remotely start and stop the planning process:# where dashboard is an instance of elasticroute.clients.DashboardClient and date is a string in YYYY-MM-DD formatdashboard.stops.start_planning(date)dashboard.stops.stop_planning(date)Quick Start Guide (Routing Engine API)The Routing Engine API is only available by request; please get in touch with us if you require our headless routing capabilities. Attempting to use the Routing Engine API with an unauthorized API Key will result in your requests being rejected.If you haven't already, install this library:pip install elasticroute>=2.0.0Create an instance ofRoutingClient, passing your API key in the constructor:fromelasticroute.clientsimportRoutingClientrouter=RoutingClient("YOUR_API_KEY_HERE")Create a newPlanobject:fromelasticroute.routingimportPlanplan=Plan("some-unique-id")Give us a list of stops:fromelasticroute.routingimportStopplan.stops=[Stop({"name":"Changi Airport","address":"80 Airport Boulevard (S)819642",}),Stop({"name":"Gardens By the Bay","lat":"1.281407","lng":"103.865770",}),# add more stops!# both human-readable addresses and machine-friendly coordinates work!]Give us a list of your available vehicles:fromelasticroute.routingimportVehicleplan.vehicles=[Vehicle({"name":"Van 1"}),Vehicle({"name":"Van 2"}),]Give us a list of depots (warehouses):fromelasticroute.routingimportDepotplan.depots=[Depot({"name":"Main Warehouse","address":"61 Kaki Bukit Ave 1 #04-34, Shun Li Ind Park Singapore 417943",}),]Set your country and timezone:plan.generalSettings["country"]="SG"plan.generalSettings["timezone"]="Asia/Singapore"Use the client to submit the plan:plan=router.plans.create(plan)The planning process is asynchronous as it takes some time to complete. Persist the value of the plan id you used earlier, and retrieve it in a separate process at a later time:plan=router.plans.retrieve(plan_id)plan.statusshould give you"planned"when the process is complete. Inspect the solution:forstopinplan.stops:print("Stop{}will be served by{}at time{}".format(stop["name"],stop["assign_to"],stop["eta"]))Advanced UsageSetting time constraintsTime constraints for Stops and Vehicles can be set with thefromandtillkeys ofelasticroute.common.Stop, and theavail_fromandavail_tokeys ofelasticroute.common.Vehicle:morning_only_stop=Stop()morning_only_stop["name"]="Morning Delivery 1"morning_only_stop["from"]=900morning_only_stop["till"]=1200# add address and add to plan...morning_shift_van=Vehicle()morning_shift_van["name"]="Morning Shift 1"morning_shift_van["avail_from"]=900morning_shift_van["avail_till"]-1200# add to plan and solve, or upload to dashboard using DashboardClientelasticroute.common.Stopis the parent class ofelasticroute.routing.Stopandelasticroute.dashboard.Stop; Vehicles work in a similar mannerSetting home depotsA "home depot" can be set for both Stops and Vehicles. A depot for stops indicate where a vehicle must pick up a stop's goods before arriving, and a depot for vehicles indicate the start and end point of a Vehicle's journey (this implicitly assigns the possible jobs a Vehicle can take).
By default, for every stop and vehicle, if the depot field is not specified we will assume it to be the first depot.common_stop=Stop()common_stop["name"]="Normal Delivery 1"common_stop["depot"]="Main Warehouse"# set stop addressrare_stop=Stop()rare_stop["name"]="Uncommon Delivery 1"rare_stop["depot"]="Auxillary Warehouse"# set stop addressmain_warehouse_van=Vehicle({"name":"Main Warehouse Van","depot":"Main Warehouse"})aux_warehouse_van=Vehicle({"name":"Auxillary Warehouse Van","depot":"Auxillary Warehouse"})# if using DashboardClient:dashboard.stops.create(common_stop)dashboard.stops.create(rare_stop)dashboard.vehicles.create(main_warehouse_van)dashboard.vehicles.create(aux_warehouse_van)# if using RoutingClient:plan=Plan("my_plan")plan.stops=[common_stop,rare_stop]plan.vehicles=[main_warehouse_van,aux_warehouse_van]plan.depots=[Depot({"name":"Main Warehouse","address":"Somewhere"}),Depot({"name":"Auxillary Warehouse","address":"Somewhere else"})]router.plans.create(plan)For this to work, there must be a corresponding depot with the same name in the dashboard (if usingDashboardClient) or in the same plan (if usingRoutingClient)Setting load constraintsEach vehicle can be set to have a cumulative maximum weight, volume and (non-cumulative) seating capacity which can be used to determine how many stops it can serve before it has to return to the depot. Conversely, each stop can also be assigned weight, volume and seating loads.
The keys areweight_load,volume_load,seating_loadfor Stops andweight_capacity,volume_capacityandseating_capacityfor Vehicles.