HERE Tour Planning API: Developer insights and best practices

The HERE Tour Planning API helps developers solve complex vehicle routing problems (VRP), from multi-vehicle route optimization to last-mile delivery, pickup and delivery, and capacity or time-window constraints. Within the HERE developer community, developers ask practical questions about fleet capacity, service scheduling, delivery constraints, driver safety and operational efficiency.

This article highlights practical HERE Tour Planning API use cases and implementation patterns drawn from those discussions.

Real-world use cases:

Modeling service technicians who perform multiple tasks at one location

For example, a field service company needed to schedule technicians visiting customer sites where several tasks could be completed during one visit. The challenge was separating:

• Fixed setup time (eg, parking, unloading equipment and check-in)

• Actual task execution time

Without this distinction, service durations became inaccurate.

Recommended approach

• Use location-specific parking durations when setup time varies by location

• place.duration for each service activity

Example

Define shared parking durations:

"shared": {
  "parking": [
    {
      "id": "parking_downtown",
      "places": [
        {
          "duration": 90,
          "vehicleTypeIds": ["small_van_experienced"]
        },
        {
          "duration": 180
        }
      ]
    }
  ]
}

Copy

Reference the parking definition in the job:

"places": [
  {
    "location": {
      "lat": 52.5293,
      "lng": 13.3850
    },
    "duration": 300,
    "parkingIds": ["parking_downtown"]
  }
]

Copy

Multiple jobs at the same customer location

A utility company frequently scheduled several tasks at one address. Without special handling:

• Service durations accumulated unnecessarily

• Stop times became inflated

Recommended approach

Use clustering together with serviceTimeStrategy=maxDurationStrategy when multiple jobs occur at the same customer location. This ensures the clustered jobs are executed during a single stop, with the service duration set to the longest duration among the clustered jobs rather than the sum of all durations. For customer-specific service durations, House Keys can further prevent service times from accumulating unnecessarily.

Delivering different product types in the same vehicle

A distributor operated vehicles carrying:

• Frozen goods

• Dry goods

• Fragile products

Each compartment had different capacity limitations.

Recommended approach

• Use multi-dimensional capacities

• Skills and/or mixing restrictions to enforce compatibility rules

Example

"capacity": [1000,500,200]

Combined with matching job skills.

Optimizing routes while avoiding restricted areas

A logistics provider needed optimized routes while avoiding:

• Construction zones

• Restricted neighborhoods

• Hazardous areas

Recommended approach
HERE Tour Planning uses HERE Routing internally during optimization and can now return route polylines as part of the optimization result. This is the recommended approach because it preserves the routing settings used during optimization and eliminates the need to recreate them in a separate Routing API request.

Use the Routing API separately only when you need additional routing capabilities, such as custom route calculations or navigation-specific features.

Managing delivery zones with geographic territories

A delivery operation divided its service area into geographic zones, with specific vehicles assigned to each territory. The goal was to keep vehicles within their assigned areas while allowing more flexibility when workload or vehicle availability changed.

Recommended approach

Use territories to define geographic service areas and control which vehicles can serve jobs within each area. Start with strict territories when vehicles should only serve their assigned zones. If operational flexibility is needed, configure flexible territories so vehicles can also serve jobs outside their primary territory when required.

This allows you to:

• Keep vehicles focused on their assigned service areas

• Balance workload across territories when needed

• Use available vehicles more flexibly

• Adapt territory restrictions to changing operational needs

Balancing fleet size against operating costs

A transportation company wanted to minimize the number of vehicles used each day. However, the optimizer was creating multiple tours even though vehicle capacity allowed jobs to be combined.

The challenge

The optimization objectives were configured as:

"objectives": [
  { "type": "minimizeUnassigned" },
  { "type": "minimizeCost" },
  { "type": "optimizeTourCount", "action": "minimize" }
]

Copy

Because vehicle costs were set to zero, the solver had no penalty for creating additional tours. Because HERE Tour Planning evaluates objectives lexicographically, the solver first optimizes for unassigned jobs, then for cost. If it finds a lower-cost solution, it may never evaluate optimizeTourCount.

Recommended approach

When minimizing fleet size is important:

• Place optimizeTourCount before minimizeCost

• Order objectives according to your business priorities

Example

"objectives": [
  { "type": "minimizeUnassigned" },
  { "type": "optimizeTourCount", "action": "minimize" },
  { "type": "minimizeCost" }
]

Copy

Handling cost-based vehicle selection across different fleet types

A fleet operator had:

• Economy vehicles

• Standard vehicles

• Premium vehicles

and wanted the optimizer to automatically choose the most cost-efficient option.

Recommended approach

Define cost parameters for each vehicle type based on its operating characteristics.

Example

"economy": {
  "costs": {
    "fixed": 30,
    "distance": 0.003,
    "time": 0.006
  }
},
"standard": {
  "costs": {
    "fixed": 50,
    "distance": 0.002,
    "time": 0.005
  }
},
"premium": {
  "costs": {
    "fixed": 80,
    "distance": 0.0015,
    "time": 0.004
  }
}

Copy

The solver evaluates:

• Fixed cost

• Distance cost

• Time cost

when selecting most appropriate vehicle for each tour.

Scheduling recurring collections throughout the week

A waste management company needed recurring collections while ensuring enough time between visits.

Challenge
There is currently no documented feature for enforcing a minimum elapsed time between independent recurring jobs. Time windows remain the primary mechanism for approximating visit spacing.

Recommended approach
Design recurring visits using carefully planned time windows. For example:

Monday 08:00–12:00
Wednesday 08:00–12:00
Friday 08:00–12:00

Reducing road crossings for curbside operations

A waste collection fleet wanted vehicles to service addresses from the preferred side of the road, reducing unnecessary street crossings and improving driver safety.

Recommended approach

Use "sideOfStreetHint" This helps route vehicles to the preferred side of the road, helping the optimizer create safer and more practical service sequences.

Designing multi-stop collection routes feeding a central hub

A common logistics pattern involves:

Depot -> Pickup A -> Pickup B -> Pickup C -> Central Hub

Developers initially model the hub as a delivery job. However, when every vehicle finishes its route at the same facility, this can add unnecessary complexity to the optimization problem.

Recommended approach

When all collected items are ultimately returned to a central facility:

• Configure the hub as the vehicle's shift end location

• Use pickup jobs for collection activities

• Only model the hub as a separate job when it has its own operational constraints or service requirements

HERE Tour Planning API FAQs from the HERE developer community:

1. How do I troubleshoot REACHABLE_CONSTRAINT errors when a location appears reachable?

A common HERE Tour Planning API issue is receiving:

{
  "code": "REACHABLE_CONSTRAINT",
  "description": "location unreachable"
}

Copy

even though the location appears reachable on the map.

Common causes reported by community members include:

• Delivery access restrictions near the destination

• Temporary road closures or live traffic events

• Last-meter connectivity issues (the stop is slightly off the routable road network)

• Vehicle profile restrictions (truck vs. car routing)

• Avoid areas or routing constraints blocking access

Troubleshooting steps:

• Verify stop coordinates and road snapping

• Test the location with the same vehicle profile in the Routing API

• Review truck access restrictions near the destination

• Test with and without live traffic enabled

• Check avoid areas and routing restrictions

• Move the stop coordinates a few meters and rerun the optimization

• Also, check out this press release for last meter guidance

2. How do soft time windows affect route optimization and constraint prioritization?

Soft time windows are often used when a preferred service time exists, but arriving slightly earlier or later is acceptable.

What's happening?

Unlike hard time windows, soft time windows do not make a solution infeasible when violated. Instead, they introduce a penalty that the solver considers during optimization.

Key behaviors:

• Soft time windows consist of a hard time window and a preferred service time

• The preferred service time may be violated if it results in a better overall solution

• The hard time window must still be respected; otherwise, the job becomes unassigned

• Soft time windows never override hard constraints

• Capacity, vehicle assignment, driver limits, and route feasibility always take priority

Best practices

• Use hard time windows when timing is mandatory

• Use soft time windows when some scheduling flexibility is acceptable

• Expect deviations when they help satisfy higher-priority constraints

• Consider adding optimization objectives that penalize soft time window violations when minimizing deviations is important.

Example
A delivery should ideally occur between 9:00–10:00 AM, but can still be completed later if required to satisfy vehicle capacity or route constraints.

3. How can I ensure lower-priority jobs don't impact higher-priority deliveries?

Many fleet operators use priorities to distinguish between must-complete jobs and optional work. However, they may notice that adding lower-priority jobs can unexpectedly increase the number of unassigned higher-priority jobs.

What's happening?

By default, HERE Tour Planning prioritizes serving higher-priority jobs during optimization. Lower-priority jobs should not displace higher-priority ones unless the optimization objectives have been configured to prioritize other goals (such as minimizing unassigned jobs) ahead of job priorities.

Job priorities are evaluated alongside other operational constraints, including:

• Vehicle capacity

• Driver working time

• Time window feasibility

• Skills and assignment constraints

It's also worth noting that using more than two distinct priority levels is currently a BETA feature. BETA features are in end-stage development and have no major bugs, but their coverage, quality, performance, or test coverage may not yet be final.

Recommended approach

• Use only two priority levels when possible (for example, critical vs optional)

• Use job priorities to distinguish between critical and less critical work.

• When configuring optimization objectives, verify that they align with your business priorities.

• If using multiple priority levels, be aware that this functionality is currently in BETA.

Example
A delivery company classifies:

Priority 1–4 = committed customer deliveries

Priority 5 = optional early deliveries

When Priority 5 jobs are included in the same optimization request, they may consume capacity and scheduling flexibility, resulting in more Priority 4 jobs becoming unassigned.

Conclusion

Whether you're solving a Vehicle Routing Problem (VRP), optimizing delivery routes, scheduling field service technicians, or improving fleet use, the HERE Tour Planning API supports modeling real-world operational constraints and generating efficient routing plans across a fleet.

The examples from the HERE Developer Community show that route optimization is about more than finding the shortest route. Accurate planning depends on modeling your business rules, vehicle constraints, costs, capacities and service requirements.

If you're working on routing, logistics, dispatch, or fleet optimization challenges, visit the HERE developer community to learn from other developers, see practical implementation examples and get more from the HERE Tour Planning API.

References

• HERE Tour Planning API developer guide

• HERE Tour Planning API demo

• HERE Tour Planning FAQs