How to optimize routes and schedules for workers with Route Planner API

When you have a company that provides service and maintenance for businesses, buildings, or people you, probably, know that finding the best schedules and optimal routes, considering all wishes, requirements, and availabilities is a puzzle. It can take quite a lot of time until you find a solution that fits all requirements.

Fortunately, the task is well-known and there are many algorithms that can find an optimal route and schedules considering all provided constraints.

Geoapify Route Planner API is one of them and does the job very well! In this article, we would like to provide you a live demo, code samples, and instruction on how to develop custom route optimization solutions.

Playground: optimize routes and schedules for workers

The playground below generates an optimization task. It emulates the daily business of a company offering household appliance repair services.

In short terms, the Route Optimization API get the following data as input:

• 5 specialists with different working times and capabilities
• 20 locations with different job duration and requirements
• the locations, job requirements, and agent skills are set randomly

The solution shows optimized routes for workers. Show/hide separate routes with an "eye" button. Get information about locations and waypoints by hovering them.

As we set quite strict constraints, some locations might be not served by specialists. You can see them on the map as orange points.

Try to generate the task for different visible areas.

Describe the task in terms of Route Planner API

Now, let's translate the scenario above to terms of Route Planner API:

• agents - specialists or workers, those time need to be optimized. Agents can have capabilities that represent skills or tools available.
• mode - transportation or travel mode for agents. Could be "drive", "truck", "walk", or "bicycle";
• jobs - planned jobs. Each job has a location and may have requirements.

How to specify an agent start and end position?

The API supports individual start and end positions for agents. For example, this can be a living place of agents or a vehicle parking place. The location can be defined as latitude and longitude coordinates or as a reference to a location specified in locations input.

How to provide address information and comments for a job?

The address information and job instructions can be a part of the description field of a job. Moreover, using the locations input you can refer to a location with the id parameter.

How to add breaks?

You can specify agent breaks time windows and their duration. You can add one or multiple breaks for every agent.

How to assign a job to the exact agent?

The requirements and capabilities objects can be used to assign the exact agent to the job. For example, you can add "agentA" as a capability to an agent and "agentA" as a requirement to the job.

This also can be useful when you need to partially recalculate the results. For example, when you add a new shipment or after a manual edit.

Solve the Route and Schedule Optimization task and visualize results

The Route Planner API works via HTTP POST. It's cross-platform and can be used with any programming language. Learn more about Route Planner API specification on the API documentation page >>

We've prepared JavaScript code samples for you to help you implement a custom solution.

Here is a JSFiddle containing the code samples.

Build a request object

• The task input JSON object contains agents and jobs lists, and mode;
• The agents have the time_windows parameter that defines availability time;
• Jobs have requirements and agents capabilities:

const serviceJobsOptimizationInput = {
  "mode": "drive",
  "agents": [
    {
      "start_location": [
        5.586790932250917,
        45.36538915
      ],
      "end_location": [
        5.586790932250917,
        45.36538915
      ],
      "time_windows": [
        [
          3600,
          10800
        ]
      ],
      "capabilities": [
        "Cooling system tester",
        "Motor locking tool"
      ]
    },
    ...
  ],
  "jobs": [
    {
      "location": [
        5.587157987701584,
        45.3692519
      ],
      "duration": 1800,
      "requirements": [
        "Electrician"
      ]
    },
    {
      "location": [
        5.588772879745656,
        45.367290249999996
      ],
      "duration": 1800,
      "requirements": [
        "Cooling system tester",
        "Motor locking tool"
      ]
    },
    ...
  ]
}

Call Route Planner API

Make an HTTP POST call with the "Content-Type=application/json" header:

fetch(`https://api.geoapify.com/v1/routeplanner?apiKey=${myAPIKey}`, {
  method: "post",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(serviceJobsOptimizationInput),
})
  .then((res) => res.json())
  .then((res) => console.log(res));

Analyze results

The Route Planner API result contains an extended by properties GeoJSON.FeatureCollection object where every feature represents an agent execution plan.

The feature properties contain information that describes the agent waypoints and way legs, route time and distance, as well as actions:

• action - single operations. The type parameter of the action contains the type of the action - start, job, or end.

{
  "index": 1,
  "type": "job",
  "start_time": 3649,
  "duration": 1800,
  "job_index": 3,
  "waypoint_index": 1
}

• waypoints - route stops, required to perform one or multiple actions:

{
  "original_location": [
    5.590781375689465,
    45.3654216
  ],
  "location": [
    5.590781,
    45.365422
  ],
  "start_time": 3649,
  "duration": 1800,
  "actions": [
    {
      "index": 1,
      "type": "job",
      "start_time": 3649,
      "duration": 1800,
      "job_index": 3,
      "waypoint_index": 1
    }
  ],
  "prev_leg_index": 0,
  "next_leg_index": 1
}

• legs - routes between waypoints:

{
  "time": 52,
  "distance": 409,
  "from_waypoint_index": 1,
  "to_waypoint_index": 2,
  "steps": [
    {
      "from_index": 0,
      "to_index": 1,
      "time": 52,
      "distance": 409
    }
  ]
}

Besides, the FeatureCollection object is extended by the properties. The properties contain the task input and may have issues. The issues indicate problems that appeared by solving the task - unassigned agents and unassigned jobs:

"issues": {
  "unassigned_jobs": [
    7,
    11,
    12,
    13,
    14,
    16,
    18,
    19
  ]
}

Visualize the results with MapLibre GL (an open-source fork of Mapbox GL)

Here is a JSFiddle that shows how to visualize the results with MapLibre GL map library:

What's next

• Learn more about Route Planner API >>
• Learn how to optimize delivery routes >>
• Learn about optimizing bus routes with Route Planner API
• Learn about Truck Route optimization
• Try more optimization scenarios on the Playground page >>
• Check the Route Planner API specification >>

Find the best routes and schedules for your workers with Route Planner API

Start now for Free and upgrade when you need it!

Get API key

Docs

Pricing