Route Planner API

The Route Planner API allows developers to integrate route planning and schedule optimization functionality into their applications. With this API, users can obtain the optimal routes between multiple locations and for multiple vehicles or agents.

The Route Planner API has been specifically developed to tackle various types of route planning challenges, such as the Travelling Salesman Problem (TSP), Capacitated VRP (CVRP), VRP with Time Windows (VRPTW), Multi-depot Heterogeneous Vehicle VRPTW (MDHVRPTW), Pickup-and-delivery problem with Time Windows (PDPTW), and etc. This API offers a comprehensive solution for optimizing routes and streamlining transportation operations for businesses and organizations of all sizes.

The API accepts input parameters such as locations, amounts, time frames, etc. The API then returns the optimized order of locations as a result. So the Route Planner helps you to solve delivery and route optimization problems for multiple vehicles.

• Authentication and API key
• API reference: inputs
• API reference: outputs
• Solving a route optimization task
• Code samples
• Pricing

In the Route Optimization API Playground, you can experiment with various popular route optimization scenarios to see how this API can help streamline your operations:

Authentication and API key

To start using the Route Planner API, you will need to obtain an API key. Fortunately, you can easily register for a free Route Planner API Key without needing a credit card.

Our free plan lets you start immediately without worrying about costs. Then, when your project requirements grow, you can upgrade to a paid plan to access additional features and resources. To learn more about our pricing options, please visit the Pricing page.

Follow these simple steps to get a Geoapify API key:

1. Head over to the Geoapify MyProjects page and create a new account.
2. Create a new project and navigate to the API Keys section. An API key will be generated automatically for you, but you can generate multiple keys per project if needed.
3. Optionally, you can protect the API key by specifying allowed IP addresses, HTTP referrers, origins, and CORS.
4. Select the "Route Planner API" and an API key to generate a URL and programming code.
5. Click the "Try" button to execute the API call and view an example of the result object.

API reference: inputs

The Route Planner API operates through HTTP POST requests that receives input data within the request body. Its API parameters enable users to optimize deliveries of bulk or discrete goods and schedule service, maintenance, and repair tasks.

Request URL

You can access the Geoapify Route Planner API via a POST request to the endpoint located at https://api.geoapify.com/v1/routeplanner.

This endpoint allows users to send input data in JSON format and receive optimized route planning solutions for deliveries or other similar tasks.

HTTP POST https://api.geoapify.com/v1/routeplanner
HEADERS 'Content-Type: application/json'

Request URL parameters

To request the Geoapify Route Planner API, you only need to provide one URL parameter - their API key.

Request body parameters

The API input parameters you need to specify in the request body:

Please note that every task submitted to the Geoapify Route Planner API must include at least one of the following lists: jobs or shipments. However, it's possible to have both shipments and jobs in the same task.

In addition, you can also specify additional route parameters. These parameters allow users to customize their route planning solutions further. Below is a list of supported parameters:

Agent object

An agent represents a resource requiring route and time planning, such as experts, workers, or vehicles:

Please note that the time_windows object in the request body contains relative time. For example, the time value "0" can correspond to the start of a day, the beginning of a working day, or any other specific time.

When dealing with bulky goods shipments, it is essential to note that goods for pickup cannot be mixed with goods for delivery. Both the pickup_capacity and delivery_capacity parameters can still be used in the task description. However, it should be assumed that the goods to be picked up and the goods to be delivered will be kept in separate containers.

For example, if an agent has a 1000 pickup capacity and a 1000 delivery capacity, this means that they have two containers: one containing 1000 units of goods and the other one empty. When they deliver 200 units and pick up 100 units at the next job, the containers will contain 800 and 100 units, respectively. This ensures that the picked up and delivered goods are not mixed up."

Break object

The break object specifies breaks and interruptions during working hours in a more flexible manner. Each break includes a desired duration and a list of time_windows, which represent the time intervals during which the break can take place.

The Route Planner API will try to choose the optimal time window for the break that fits best with the agent's route. This object can help to ensure that the agent's working hours are efficiently scheduled and that necessary breaks are taken at appropriate times.

Job object

The jobs object represents a list of delivery or service jobs that an agent needs to perform:

Shipment object

The shipment object represents the delivery of goods from one location to another location. It is similar to the job object but separately describes pickup and delivery locations:

Location object

When using the Geoapify Route Planner API, you can specify a list of locations for repeated locations. This is particularly useful when describing the locations of warehouses or other repeated destinations, as it allows you to optimize the number of locations that the route planner will consider.

Below is a sample request for a Route Planner API:

POST https://api.geoapify.com/v1/routeplanner?apiKey=YOUR_API_KEY
Content-Type=application/json

{
   "mode":"drive",
   "agents":[
      {
         "start_location":[
            13.381453755359324,
            52.520666399999996
         ],
         "time_windows":[
            [
               0,
               7200
            ]
         ]
      },
      ...
   ],
   "shipments":[
      {
         "id":"order_1",
         "pickup":{
            "location_index":0,
            "duration":120
         },
         "delivery":{
            "location":[
               13.381175446198714,
               52.50929975
            ],
            "duration":120
         }
      },
      ...
   ],
   "locations":[
      {
         "id":"warehouse-0",
         "location":[
            13.3465209,
            52.5245064
         ]
      }
   ]
}

You can generate request objects using the API Playground that encompass the most common route optimization tasks.

API reference: outputs

The API returns a GeoJSON FeatureCollection object, with each feature representing an agent's plan.

Each feature, which is essentially an agent plan, provides comprehensive data regarding route legs, steps, and waypoints associated with job locations, as well as a list of actions that the agent must execute.

Furthermore, the FeatureCollection object incorporates the "properties" object, which holds the input parameters and any issues that arise during task resolution.

Issues object

The Route Planner Issues object returned by a Route Planner API contains information about any issues that occurred during the planning process.

The Issues object may include information about the following types of issues:

Agent plan object (GeoJSON Feature properties)

Within the feature properties, there is data about the agent's route and the execution of jobs:

Action object

Contains single operation information:

Waypoints

Contains information about a waypoint location and works planned in the location:

RouteLeg object

Contains information about a route between 2 locations:

LegStep object

Contains information about a separate step of RouteLeg:

Here is an example of Route Optimization result object:

{
   "type":"FeatureCollection",
   "properties":{
      "mode":"drive",
      "params":{
         "mode":"drive",
         "agents":[...],
         "shipments":[...],
         "locations":[...]
      },
      "issues":{
         "unassigned_shipments":[ 17 ],
         "unassigned_agents": [ 4 ]
      }
   },
   "features":[ ... ]
}

Here is an example of Agent Plan Feature:

{
    "geometry":{
      "type":"MultiLineString",
      "coordinates":[...]
    },
    "type":"Feature",
    "properties":{
      "agent_index":0,
      "time":10775,
      "start_time":0,
      "end_time":10775,
      "distance":19203,
      "legs":[
          {
            "time":44,
            "distance":391,
            "from_waypoint_index":0,
            "to_waypoint_index":1,
            "steps":[
                {
                  "from_index":0,
                  "to_index":1,
                  "time":44,
                  "distance":391
                }
            ]
          },
          ...
      ],
      "mode":"drive",
      "actions":[
          {
            "index":0,
            "type":"start",
            "start_time":0,
            "duration":0,
            "waypoint_index":0
          },
          {
            "index":1,
            "type":"pickup",
            "start_time":44,
            "duration":120,
            "shipment_index":19,
            "shipment_id":"order_20",
            "waypoint_index":1
          },
          ...
      ],
      "waypoints":[
          {
            "original_location":[
                13.3908216,
                52.5194189
            ],
            "location":[
                13.390822,
                52.519419
            ],
            "start_time":0,
            "duration":0,
            "actions":[
                {
                  "index":0,
                  "type":"start",
                  "start_time":0,
                  "duration":0,
                  "waypoint_index":0
                }
            ],
            "next_leg_index":0
          },
          ...
      ]
    }
}

Solving VRP-related tasks

The Route Planner is flexible and has the needed parameters to let you solve a wide range of vehicle routing problems. Here are some quick tips and tricks that will help you define input parameters.

Shipping Bulky Goods

When using the Route Planner API to plan the delivery or pickup of bulky goods, keep the following in mind:

• Use the agent's delivery_capacity / pickup_capacity t define the agent's capacity and the job's delivery_amount / pickup_amount or shipment's amount parameters to determine the shipment amount.
• It is assumed that the agents are fully loaded for delivery-related tasks at the start location. For example, if the task is to deliver heating oil, the vehicle will be considered full at the start position, with the amount specified in delivery_capacity.
• It is assumed that the agents are empty at the start location for pickup-related tasks and can carry up to the amount specified in pickup_capacity at the end position.
• If the agents need to perform multiple iterations to complete all jobs, create additional virtual agents with their starting position at the end location.

Suppose, for instance, you have three Waste Collector Trucks with a collection capacity of 5000l each (15000l in total), and you need to collect 20000l of waste. In that case, one of the trucks will need to make an extra trip to complete all the jobs. To accomplish this, you can generate an additional agent that will commence from a Waste Recycling Plant (where the other agents have their End location). This way, one of the trucks can perform the second iteration planned for the additional agent.

Shipping Individual / Discrete Items

The Route Planner API can also solve tasks involving the delivery or pickup of discrete items. Here are some guidelines to follow:

• Use shipments to specify the items to deliver or pick up.
• If necessary, include jobs in the task to specify additional actions.
• Use locations to add repeated places, such as a storage facility or warehouse.
• Specify capabilities and requirements for agents and jobs, if necessary, to fulfill tasks with unique requirements such as "extra-long," "fragile," or "dangerous."
• By default, the API optimizes resources (agents). To ensure that the jobs are completed within a specific time frame, set the agent's time_windows accordingly.

Resouce management

With the Route Planner API, you can effectively manage resources (agents) based on their capabilities and available hours. Here's how:

• Utilize the agent's capabilities and the job's requirements to specify features, tools, or specific knowledge.
• Set time_windows for both agents and jobs to specify the required and available time slots.
• Ensure that you set the job durations for each job.

Modifying the Execution Plan

In certain cases, modifying the existing route plan may be necessary by adding additional jobs or reassigning certain jobs and optimizing the routes again. You can easily achieve this with the following steps:

• Add the agent identifier as a capability for each agent.
• Add the agent identifier as a requirement to each job where an agent is already assigned.
• Solve the task with the new input parameters.

Code samples

Visualizing Agent Waypoints

The agent's route consists of waypoints or planned jobs and route legs between waypoints. Below is a code sample of how to visualize an agent's waypoints using the MapLibre GL / Mapbox GL library:

routePlans.forEach((agentPlan) => {
  const items = agentPlan.waypoints.map((waypoint, index) =>
    point(waypoint.location, { index: index + 1 })
  );

  // create points source + layer
  map.addSource(`waypoints-of-agent-${agentPlan.agentIndex}`, {
    type: "geojson",
    data: featureCollection(items),
  });

  map.addLayer({
    id: `waypoints-of-agent-${agentPlan.agentIndex}`,
    type: "circle",
    source: `waypoints-of-agent-${agentPlan.agentIndex}`,
    paint: {
      "circle-radius": 10,
      "circle-color": color, // set any color here
      "circle-stroke-width": 1,
      "circle-stroke-color": darker_color, // set a darker color here
    },
  });

  map.addLayer({
    id: `waypoints-text-of-agent-${agentPlan.agentIndex}`,
    type: "symbol",
    source: `waypoints-of-agent-${agentPlan.agentIndex}`,
    layout: {
      "text-field": "{index}",
      "text-allow-overlap": false,
      "text-font": ["Roboto", "Helvetica Neue", "sans-serif"],
      "text-size": 12,
    },
    paint: {
      "text-color": textColor, // set contrast to the color textColor
    },
  });
});

Visualize agent route legs

The Route Planner API uses the Route Matrix API, which operates with time and distance values. The API result includes an order of waypoints but not the actual route geometry. Call the Routing API with the agent waypoints to visualize the agent route and construct the route geometry:

routePlans.forEach((agentPlan, index) => {
  const waypoints = agentPlan.waypoints.map(waypoint => waypoint.location as Position);

  generateRoute(waypoints, travelMode /* 'drive', 'truck', ...*/).then((routeData: FeatureCollection) => {
    const layerId = `agent-route-${index}`;
    agentPlan.routeLayer = layerId;
    map.addSource(layerId, {
      type: 'geojson',
      data: routeData as any
    });

    map.addLayer({
      'id': layerId,
      'type': 'line',
      'source': layerId,
      'layout': {
        'line-cap': "round",
        'line-join': "round"
      },
      'paint': {
        'line-color': color
      }
    });
    
    return layerId;
  })
});

function generateRoute(points: Position[], mode: string) {
  const waypoints = points.map(position => position[1] + ',' + position[0]).join('|');
  let url = `https://api.geoapify.com/v1/routing?waypoints=${waypoints}&mode=${mode}&apiKey=${apiKey}`;

  return fetch(url).then((resp) => resp.json());
})

Pricing

Geoapify applies credit-based pricing for API usage. We provide various Pricing Plans based on the daily credit consumption. Our pricing plans begin with a free plan that offers 3000 daily credits. You can start with the free plan and upgrade as your business grows.

Since the Route Planner API involves Route Matrix API calls, the credit consumption per API call depends on the number of locations specified in the input parameters, which include:

• Agent start locations
• Agent end locations
• Shipment pickup and delivery locations
• Job locations

We apply the following rules to calculate the credit consumption for the Route Planner API:

Below are rules we use for calculating call costs for the Route Planer API:

Example 1

The Route Planner task that contains 2 agents with start locations only and 7 jobs (9 locations in total) will cost 9*9 = 81 credits.

Example 2

The Route Planner task that contains 10 agents with start and end locations and 50 jobs (10 * 2 + 50 = 70 locations in total) will cost 70*10 = 700 credits.

Example 3

The Route Planner task that contains 5 agents with start and end locations and 30 shipments (10 * 2 + 30 * 2 = 80 locations in total) will cost 80*10 = 800 credits.