Find answers to frequently asked questions

API Features and restrictions

Question	Answer
Are there any limits regarding the number of vehicles, vehicle types, and the number of jobs for the synchronous and asynchronous request flow?	Yes. For more information on the limits for each request type, see Synchronous and asynchronous endpoint comparison.
How does Tour Planning handle traffic information in routing calculations?	Traffic information can be considered by HERE Tour Planning in three ways - automatically, by live or historical data, and by historical data only. Search for the `traffic` parameter in our API reference for more details (`configuration.fleet.traffic`).
Does HERE Tour Planning API have any restrictions on the geographic distribution of locations included in a problem definition, for example, a maximum distance between vehicle or job locations?	Tour Planning does not have any restrictions on the maximum distance for routing. However, when exceeding a 490 km radius (or 980 km in bounding box diameter), no live traffic will be taken into account by default (see the `traffic` parameter in our API reference). You can enforce having live traffic always, but then you should make sure that all the locations in the problem you specify are within an enclosing circle with a radius of 490 km or less. If they are not, you will receive a response with a status code 400, an error code E613429 and the following error message: "Region radius is too big to include traffic information". In this case, you can remove some locations (for example. by removing jobs) from the problem until all locations are within an enclosing circle with a radius not exceeding the radius limit of 490 km mentioned above, and proceed with your problem getting live traffic information.
Does HERE Tour Planning support solving Vehicle Routing Problems (VRP)?	Yes, see the Developer Guide for the detailed explanation of how to use the HERE Tour Planning for solving the most common VRPs.
Does HERE Tour Planning API support open VRP?	Yes, see Solve open vehicle routing problems for details.
Does HERE Tour Planning API support multiple shifts per vehicle?	Yes, see Multiple Shifts And Breaks for details.
Is using a custom time-distance matrix supported?	No. Your requests can only use the HERE-provided, default time-distance matrix. However, you can use a custom routing matrix. For more information, see, Routing Profile.
Does the API always serve pickup tasks before delivery tasks only if the tasks belong to the same job?	Yes. When pickups and deliveries are part of the same job (multi-job), all pickups are always scheduled before all deliveries. This rule cannot be changed, even with the `position` feature. The `position` feature can only influence the order of tasks within the pickup phase or within the delivery phase, or for tasks that belong to different jobs. For more information, see Control job task position.
How is the capacity computed in scenarios involving both delivery and pickup activities?	In case of multi-jobs (that is jobs involving pickup and delivery assignments), the API calculates the load after each activity to ensure that no capacity violations occur. For pickups, the vehicle load in increased based on the demand value in the activity. For deliveries, the API decreases the load corresponding to the demand. At no single point during the tour can the vehicle load exceed the capacity. For example, consider two multi-job tasks, each involving two pickups (`demand = 1`) and one delivery (`demand = 2`). Given a vehicle capacity of `4`, a sample solution could be as follows: `Tour Start (0) → 1st Pickup job_1 (+1, load = 1) → 2nd Pickup job_1 (+1, load = 2) → 1st Pickup job_2 (+1, load = 3) → 2nd Pickup job_2 (+1, load = 4) → Delivery job_1 (-2, load = 2) → Delivery job_2 (-2, load = 0)` In cases involving mixed independent pickup and delivery jobs, the vehicle load changes dynamically during the tour, for example, consider a sample solution with a vehicle capacity of `5`: `Tour Start (0) → Pickup job_1 (+2) → Pickup job_2 (+3) → Delivery job_2 (−3) → Delivery job_1 (−2) → Tour End (0)` When capacity constraints are applied, if the total demand exceeds the vehicle's capacity, the tour might result in unassigned jobs. In the following example, with the capacity of 5, jobs like `job_1` are left unassigned: `Tour Start (job_2 + job_3, load = 5) → Delivery job_2 (-2, load = 3) → Pickup job_4 (+1, load = 4) → Pickup job_5 (+1, load = 5) → Delivery job_3 (−3, load = 2) → Tour End (job_4 + job_5, load = 2)` In delivery-only cases, the initial load equals the sum of demands, and the final load is zero. In pickup-only cases, the initial load is zero, and the final load equals the sum of all assigned demands. For more information, see Solve the capacitated vehicle routing problem.
What happens to unassigned jobs?	The API response lists all unassigned jobs together with the reason for each job being unassigned.

General technical details

Question	Answer
Can a vehicle shift stretch over several days?	Yes, technically there is no limit for the shift length.
Can a 'break' stretch over more than 1 day?	No, there is a limit on the duration of breaks of 24 hours.
Why are there the slightly different solutions for some problems when running them several times?	The algorithm used by HERE Tour Planning API is non-deterministic.
How many pickup or delivery tasks can be added to one job?	Maximum 3 pickups and 3 delivery tasks are allowed in one multi-job. If more pickup or delivery tasks are required to be added, the problem should be formulated differently. If the pickups are from a single location and there are several deliveries, the pickup location should be handled at the client side as the vehicle shift start and individual deliveries should be added as separate jobs. It makes the problem less complex and can produce more efficient tours.
Can I ensure that all my vehicles are used in a tour?	Yes, you can maximize the number of vehicles assigned to serve jobs within a tour through the `optimizeTourCount.maximize` objective. For more information, see Objectives. Note that the HERE Tour Planning API uses a hierarchical order of objectives, requiring you to specify additional objectives before the `optimizeTourCount` objective.
Is it necessary to include the `minimizeCost` objective in the `objectives` array? And if the default cost definition prioritizes time, does that mean I don't need to explicitly add `minimizeDuration` to my `objectives` list?	Including the `minimizeCost` objective in the `objectives` array is mandatory along with `minimizeUnassigned`. The default objectives prioritize minimizing unassigned jobs, optimizing tour count, and minimizing cost, in that order. If your optimization requires prioritizing time (duration), you must add the `minimizeDuration` objectives to the objectives list to ensure it is considered according to your business objectives. For more information, see Objectives.
If a customer is to receive two parcels, should they be specified as two separate job tasks in the problem?	Yes, you can specify each parcel delivery as an individual task with the corresponding demand value. However, HERE recommends preprocessing these two tasks by combining them into a single task, with the demand value equal to the sum of the individual task demands. Ensure that the combined task does not exceed the capacity of the vehicle type serving that task.
What's the difference between `place.duration` and `vehicle.shift.stopBaseDuration`?	`place.duration` represents the service time required to serve a task. For example, this could involve tasks like lifting a fridge to the 5th floor without an elevator (duration = 20 – 30 minutes) or placing a letter in a mailbox (duration = a few seconds to a minute). `vehicle.shift.stopBaseDuration` is a set duration added once to each stop for a vehicle, accounting for tasks like parking or preparing for loading/unloading. It's configured per vehicle and applies to every stop the vehicle makes. For example, consider a scenario where a truck stops at a location to serve multiple pickup assignments. The `stopBaseDuration` for the truck is `3600` seconds. Each pickup (`place.duration`) takes `300` seconds. If there are five pickups at this stop, the total time spent is one hour and 25 minutes (`3600` seconds for stop base duration + `5` * `300` seconds for each pickup). For more information, see API Reference. To determine the stop `duration` based on the recipient (customer) rather than the specific item being delivered (such as parcels or letters), you can use the `serviceTimeStrategy` for job clustering and set it to `maxDurationStrategy`. Such strategy is particularly useful in delivery scenarios where the service time per task is not as important as the fact that you are delivering to the same customer. For example, in postal deliveries, whether you have 1 or 5 letters to deliver to a single address, the time that it takes to complete the task remains roughly the same. The `maxDurationStrategy` ensures that the total duration of jobs in the cluster equals the duration of the job with the longest duration. For example, if you deliver 3 letters (each with 60 s duration) and a parcel (120 s duration) to a single address, then, when using maxDurationStrategy, the duration of the clustered job equals 120 s, which is the longest duration within the jobs participating in the cluster. For more information, see Clustering.
How to preassign orders on vehicles?	The HERE Tour Planning API enables multiple methods of making sure vehicles are assigned specific jobs during a tour. For example, using skills is a suggested method for assigning specific jobs to certain vehicles ahead of time, even when the order of these jobs isn't predetermined. This approach guarantees that jobs are only carried out by vehicles equipped with the necessary skills (for example, `heavy-duty`, `refrigeratior`, `air-conditioned`, and so on). For more information, see Assign jobs based on skills. Territories provide another method in which you can control which vehicles are allowed or preferred to complete specific jobs based on geographic areas. For more information, see Optimize tours by territories. You can also preassign jobs to specific vehicles using the optional `relations` parameter. This parameter enables you to define rules and the order of job completion for specific vehicles, influencing the algorithm's behavior during the tour re-planning process. For more information, see Using Relations For Tour Replanning.
Can I leave the vehicle costs attribute empty or set it to a default small value (such as `0`) when the goal is to minimize total time?	Although you are allowed to set the `costs` attributes to `0`, HERE recommends explicitly setting a higher value for the `time` cost to effectively minimize the total tour time. In addition, you can also define tour objectives, in the following hierarchical order to achieve your objectives: `minimizeUnassigned`, `minimizeDuration`, `optimizeTourCount`, and `minimizeCost`. For more information, see Optimize tours for cost.
Is it possible to configure a single fleet type in the HERE Tour Planning API to accommodate vehicles with two different compartments, each having its own capacity and skills?	Yes, it is possible to use a single fleet type with different capacity configurations and skills for vehicles with multiple compartments. The suggested approach involves defining your fleet with skills such as `general` and `special`, along with their respective capacities. When planning routes, you can check if there are special products in the invoice and adjust the vehicle selection accordingly. This method allows for effective control over the capacity and skills required for different products during transportation. For more information, see Assign jobs based on skills.

Access and licensing

Question	Answer
Do I need to sign an evaluation agreement in case I want to try out HERE Tour Planning API?	Yes.
How can I get evaluation access to HERE Tour Planning API?	Please contact your regional HERE representative or directly request access via the platform portal.
How can I get commercial access to HERE Tour Planning API?	Please contact your regional HERE representative or directly proceed to the platform portal, create an account, and choose the Base plan.

Authentication and credentials

Question Answer

Where do I find information on how I can request a token or API key for accessing Tour Planning API? Getting Credentials, Identity and Access Management.

Why do requests for route polylines fail with routeDetailsUnauthorized when using an API Key with Trusted Domains enabled? When you request route polylines using "routeDetails": ["polyline"], the Tour Planning API internally calls the Routing API v8. Trusted Domains validate requests using the HTTP Referer header from browsers.

In cases when the front end passes an API Key to a server, and the server calls the Tour Planning API, it means that the internal Routing API v8 request originates from a server context. Server-to-server requests typically lack the referer header needed to match the configured trusted domains, causing the routeDetailsUnauthorized error.

This explains scenarios in which the same API Key works when it originates directly from the front end but fails when it additionally passes through a server.

To resolve this issue, use either an API Key without Trusted Domains enabled or OAuth authentication for server-to-server requests. For more information, see Get the OAuth 2.0 credentials and Obtain route polylines for the tour.

Question	Answer
Where do I find information on how I can request a token or API key for accessing Tour Planning API?	Getting Credentials, Identity and Access Management.
Why do requests for route polylines fail with `routeDetailsUnauthorized` when using an API Key with Trusted Domains enabled?	When you request route polylines using `"routeDetails": ["polyline"]`, the Tour Planning API internally calls the Routing API v8. Trusted Domains validate requests using the HTTP Referer header from browsers. In cases when the front end passes an API Key to a server, and the server calls the Tour Planning API, it means that the internal Routing API v8 request originates from a server context. Server-to-server requests typically lack the referer header needed to match the configured trusted domains, causing the `routeDetailsUnauthorized` error. This explains scenarios in which the same API Key works when it originates directly from the front end but fails when it additionally passes through a server. To resolve this issue, use either an API Key without Trusted Domains enabled or OAuth authentication for server-to-server requests. For more information, see Get the OAuth 2.0 credentials and Obtain route polylines for the tour.

Performance and rate limits

Question	Answer
What is the transaction definition?	The number of transactions charged for a request is the sum of all locations. Locations include job locations, vehicle type starting and ending locations, breaks including driver rest, charging, or other planned stops. See Tour Planning Billing for more details.
What are the rate limits for HERE Tour Planning?	2 requests per second per realm (customer), which applies to both synchronous and asynchronous endpoints. For requests over that limit we return a 429 error response.
How are compute resources for asynchronous problem computations distributed among different users?	Each user receives a fair share of the compute resources. In case your resource consumption is extremely high in comparison to other users, some of your problem computations might have to wait until a couple of your problems finish computing. This behavior merely makes sure that one or a couple of power users cannot consume all compute resources for a certain amount of time. In practice you should not notice this. Only if you have submitted an extremely large number of problems for asynchronous computation concurrently, you might see that a small number of those problem calculations remain in pending state for longer than usual. Please contact your local HERE representative, in order to discuss solutions in case you think this might be an issue.

Synchronous and asynchronous endpoint comparison

Synchronous	Asynchronous
max 500 task locations	max 7000 task locations
max 35 vehicle types	max 150 vehicle types
max 350 vehicles per vehicle type	max 350 vehicles per vehicle type
`maxTime`: max - 240 sec, default - 240 sec	`maxTime`: max - 3600 sec, default - 3600 sec
`stagnationTime`: max - 240, default - 10	`stagnationTime`: max - 3600, default - 600