kangrouter-py

Python client for KangRouter - pickup/delivery transportation services optimization.

Installation

pip install kangrouter-py

Usage

Preliminaries

For interacting with the API, both an apiKey and a licenseId are required. Please obtain them from your account page.

An example problem

Input problems are described as a python dict. As a (simplistic) example, consider the problem of:

• Taking Alberto Caeiro home after a medical appointment at the Garcia de Orta Hospital. He is ready to leave the hospital after 13:00, and must be home no later than 14:15. Alberto is on a wheelchair, so we allocate 5 minutes for pickup and dropoff.
• Picking Ricardo Reis at the Brasileira café, and take him to a beach restaurant. He wants to be there no later than 12:15. Ricardo takes a regular seat.

Assume that the vehicle available for transportation is parked in Sintra, has 3 seats and room for 2 wheelchairs.

This problem translates to the following object:

problem = {
  "nbResources": 2,
  "jobs": [
    {
      "jobId": "Pickup Alberto at the hospital",
      "origLat": "38.674921",
      "origLon": "-9.175401",
      "destLat": "38.716860",
      "destLon": "-9.162417",
      "minStartTime": "13:00",
      "maxEndTime": "14:15",
      "pickupDuration": 5,
      "deliveryDuration": 5,
      "consumptions": [0,1]
    },
    {
      "jobId": "Take Ricardo to the beach",
      "origLat": "38.710835",
      "origLon": "-9.142143",
      "destLat": "38.634080",
      "destLon": "-9.230549",
      "maxEndTime": "12:15",
      "pickupDuration": 1,
      "deliveryDuration": 1,
      "consumptions": [1,0]
    }
  ],
  "vehicles": [
    {
      "vehicleId": "12-AS-46",
      "depotLat": "38.806842",
      "depotLon": "-9.382556",
      "minStartTime": "07:00",
      "maxEndTime": "22:00",
      "maxWorkDuration": 540,
      "capacities": [2,3],
      "overspeed": 1.25
    }
  ]
}

Interesting problems have multiple jobs and multiple vehicles, but the example above should be enough to get you going.

Submit a problem

The code below creates a new solver for the provided example:

from kangrouter import KangRouterClient
api = KangRouterClient(apiKey,licenseId)
solverId = api.create(problem)

Check solving status

After a solver is created it can be in one of 4 states:

• pending - The solver is queued for execution but not started yet.
• solving - The solver is executing.
• completed - The solver has finished.
• invalid - The problem is invalid, or an unexpected error has occurred.

The function below is used to query the solver current state and obtain information regarding the solving progress:

status = api.getStatus(solverId)
print(status)

This is a very simple problem, so the solver executes very quickly:

{
  "execStatus": "completed",
  "nbJobsDiscarded": 0,
  "solverEndTime": "Wed Nov 18 11:59:48 2015 GMT",
  "solverStartTime": "Wed Nov 18 11:59:40 2015 GMT",
  "totalDistance": 98,
}

Given that larger problems may take a few minutes, calling this function while the solver is executing will also return ETA (expected delivery time) for completion.

Get the solution

When the solver is done, the solution may be retrieved as follows:

solution = api.getSolution(solverId)
print(solution)

The solution shows at what times, or time intervals, drivers must leave their depots, start their work breaks, or perform pickup/delivery actions:

{
  "jobsScheduled": [
    {
      "jobId": "Pickup Alberto at the hospital",
      "maxEndTime": "14:15",
      "maxStartTime": "13:55",
      "minEndTime": "13:20",
      "minStartTime": "13:00",
      "vehicleId": "12-AS-46"
    },
    {
      "jobId": "Take Ricardo to the beach",
      "maxEndTime": "12:15",
      "maxStartTime": "11:59",
      "minEndTime": "11:14",
      "minStartTime": "10:58",
      "vehicleId": "12-AS-46"
    }
  ],
  "type": "total",
  "vehiclesScheduled": [
    {
      "maxEndTime": "14:35",
      "maxStartTime": "11:38",
      "minEndTime": "13:40",
      "minStartTime": "10:37",
      "vehicleId": "12-AS-46"
    }
  ]
}

Other methods

The remaining methods allow to stop a running solver, which might be useful if you're in a hurry:

api.stop(solverId)

and remove a solver (and associated data) from the server:

api.delete(solverId)

Links

• KangRouter API Reference
• KangRouter API Playground