Route Planner API Specification

The API is used to solve route and resource optimization tasks. The API is implemented via an HTTP POST request.

API URL

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

Request parameters

Name Description
apiKey Geoapify API key

Request body parameters

Name Type Description
agents Agent[] An agent represents the resource which route and time should be planned (experts, workers, vehicles)
jobs Job[] The list of jobs that should be done
shipments Shipment[] The list of shipments that should be pick up/delivered. The shipments list is used to describe items that should be picked up from one location and delivered to another location.
locations Location[] The list of locations that can be referenced in jobs and shipments
mode "drive", "truck", "walk", "bicycle" Transportation or travel mode. Possible values: "drive", "truck", "walk", "bicycle"

Note! Every task should contain at least one of the lists - jobs and shipments. A task can contain both shipments and jobs.

Agent object

Name Type Description
start_location [longitude, latitude] Start location represented as an array of coordinates: [longitude, latitude]. Usually is a parking or warehouse location for vehicles, an office or home location for workers.
start_location_index number Index of the start location in the locations list
end_location [longitude, latitude] Optional end location for the agent.
end_location_index number Index of the end location in the locations list
pickup_capacity number For bulky goods shipments only! Amount of bulky goods that could be picked up by the agent.
delivery_capacity number For bulky goods shipments only! Amount of bulky goods that could be delivered by the agent.
capabilities string[] List of the agent capabilities that describe a feature, tool, or knowledge of the agent (vehicle or person). This could be any string values - 'extra-long', ''welding machine, 'electricity'. Agent capabilities should match job requirements.
time_windows [[number, number], ...] Working timeframes that are represented as pairs of relative times in seconds: [[0, 3600]] - available the first hour only, [[0, 14400], [18000, 32400]] - corresponds to 8-hours working day with 1-hour lunchtime.
breaks Break[] More flexible way of specifying breaks and interruptions during the working hours. Each break have a desired duration, and list of time_windows during which it can take place. Route planner will try to choose the optimal time window, that fits best to the agent's route.
id string Optional agent identifier, that can help to identify the agent in results
description string The agent description

Note, the time_windows object contains relative time. The time "0" can correspond to a day start, begin of a working day, or any other time.

Note, in case of bulky goods shipment, the goods to be picked up can't be mixed with the goods to be delivered. You can still use both of the "pickup_capacity" and "delivery_capacity" parameters in the task description, but assume that goods to deliver are in one container and goods to deliver in another container. For example, if an agent has 1000 pickup capacity and 1000 delivery capacity, this will mean that he has 2 containers: one of them contains already 1000 units of goods, another is empty. When at the next job he will deliver 200 units and pickup 100 units, the containers will contain 800 and 100 units - picked up and delivered goods are not mixed up.

Break object

Name Type Description
duration number The break duration in seconds.
time_windows [[number, number], ...] Time ranges during which the break can take place, represented as pairs of relative times in seconds. Examples: [[3600, 7200]] - during the 2nd hour from the beginning of working day, [[14400, 18000], [28800, 32400]] - break can take place betwen 4th and 5th working hour or between 8th and 9th working hour.

Job object

Name Type Description
location [longitude, latitude] The job location.
location_index number Index of the location in the locations list
priority number = 0..100 Job priority. By default is 0. 0 - the lowest priority, 100 - the highest priority.
duration number The job duration in seconds.
pickup_amount number For bulky goods shipments only! Amount of bulky goods to be picked up.
delivery_amount number For bulky goods shipments only! Amount of bulky goods to be delivered.
requirements string[] List of the job requirements that describe a feature, tool or knowledge that is required to make the job. This can be any string values - 'extra-long', 'welding machine', 'electricity'. Job requirements should match agent capabilities.
time_windows [[number, number], ...] Required timeframes that are represented as pairs of relative times in seconds: [[0, 3600]].
id string Optional job identifier, that can help to identify the job in results
description string The job description

Shipment object

Name Type Description
id string Required parameter, the unique identifier of a shipment.
pickup Object Pickup parameters.
pickup.location [longitude, latitude] Pickup location.
pickup.location_index number Index of the pickup location in the locations list.
pickup.duration number The pickup duration in seconds.
pickup.time_windows [[number, number], ...] Pickup timeframes that are represented as pairs of relative times in seconds: [[0, 3600]].
delivery Object Pickup parameters.
delivery.location [longitude, latitude] Delivery location.
delivery.location_index number Index of the delivery location in the locations list.
delivery.duration number The delivery duration in seconds.
delivery.time_windows [[number, number], ...] Delivery timeframes that are represented as pairs of relative times in seconds: [[0, 3600]].
requirements string[] List of the shipment requirements that describe a feature, tool or knowledge that is required to pick up or deliver the shipment. This can be any string values - 'extra-long', 'dangerous', . Shipment requirements should match agent capabilities.
priority number = 0..100 Job priority. By default is 0. 0 - the lowest priority, 100 - the highest priority.
description string The shipment description

Location object

Name Type Description
id string Location unique identifier
location [longitude, latitude] The location coordinates.

Response Object

The response contains a GeoJSON FeatureCollection object with a feature of "MultiLineString" type, which represents the agent plan. The FeatureCollection object properties contain detailed information about route legs, steps and waypoints that correspond to job locations. The structure of the Route Planner feature properties is described in the Route Planner Feature Specification.

Besides, the FeatureCollection object is enriched by the "properties" object, that contains the input parameters and may contain issues that appeared by solving the task.

Issues

Name Type Description
unassignedAgents array list of agents that do not have an execution plan (shipments or jobs)
unassignedJobs array list of jobs that are not assigned to any agent
unassignedShipments array list of shipments that are not assigned to any agent