GuidesAPI Reference
Guides
  1. Tour Planning API Developer Guide
  2. Adapt to real-world dynamics

Configure location-specific parking durations for more realistic service times

The HERE Tour Planning API enables you to assign parking durations using two complementary approaches: location-specific parking and vehicle-specific parking. You can use these features independently or combine them to model complex real-world parking scenarios.

This approach addresses variations in parking conditions at different job sites while also accounting for differences in vehicle and driver characteristics, providing the flexibility to create more accurate time estimates.

Location-specific factors

Examples of location-specific factors that can influence parking duration at or near the target job location include:

  • Parking availability: When multiple parking spots are available, drivers may require less time to find a convenient spot. Conversely, if the target location has limited or no parking options, drivers might need more time assigned for parking.
  • Parking infrastructure: Various types of parking infrastructure might influence the total duration required for the parking activity. For example, delivery trucks might take less time to park in loading docks that are designed for efficiency, as compared to street parking.
  • Loading equipment requirements: The presence, absence, or quality of loading equipment at the target location might influence the time that is necessary for the vehicle to find the appropriate parking arrangement. For example, inadequate or poorly maintained equipment might cause vehicles to park longer or seek alternative parking spots.
  • Parking location distance from service location: When parking occurs at designated coordinates separate from job service locations (for example, a parking lot 50-100m away from delivery addresses), the additional walking or travel distance from the parking spot to the actual service point and back to the parking spot after service affects routing and total tour duration. This scenario is common in urban areas with limited street parking that require the use of central parking facilities, such as when delivering to a large shopping center.

Vehicle-specific factors

Examples of vehicle-specific factors that can influence parking duration at or near the target job location include:

  • Vehicle-specific characteristics: Different vehicle types might require different parking durations. For example, a large delivery truck might need 180 seconds to park and secure, while a small van might only need 60 seconds at the same location.
  • Safety or regulatory compliance: Vehicles carrying hazardous materials might be required to park in specially designated areas, designed for quick and compliant parking.
  • Driver experience: When your fleet's drivers are familiar with the future tour area, they may be able to locate an appropriate parking spot more quickly, reducing the need for increased parking duration.
📘

Note

This is an ALPHA feature, which means it is new or experimental and under active development. Alpha features are provided for testing and feedback purposes. They may change significantly or might not become generally available.
For more information, see Explore experimental features.

Understand parking duration setup

The parking duration feature uses the following key components:

  • Shared parking definitions: Define available parking options in the shared.parking array, each with a unique id and places that contain duration, optional vehicle-specific assignments, and location.
  • Job-specific parking assignments: Reference parking options in job places by using the parkingIds array to specify the parking with specific duration that is available for that particular job.
📘

Note

Parking duration represents only the time required for parking-related activities (such as finding a spot, maneuvering, and securing the vehicle). It does not represent the total time the vehicle remains at the location. The total stop duration includes both the parking duration and all service activities at that stop.

Specifying parking location affects routing decisions and total tour metrics:

  • When parking occurs at designated coordinates separate from job sites, the vehicle routes through: previous stop → parking spot X → service stops with parking ID X → parking spot X → next stop.
  • The walking time and distance between the parking spot and all associated jobs (including from parking to the first job and from the last job back to parking) are captured in the times.intraStop and intraStopDistance fields of the tour statistics.
  • When multiple jobs share the same parking ID with specified coordinates, the parking duration is counted once per parking visit in times.stopping. If the vehicle must visit the same parking location multiple times (for example, due to job time windows), the parking duration applies to each visit.

Shared parking configuration

Define parking locations in the shared.parking array within the plan object. Each parking definition must include:

  • id (required): A unique identifier for the parking location
  • places (required): An array containing parking definitions (minimum: 1, maximum: 10 per parking ID) with:

    • duration (required): Time in seconds for parking-related activities (finding and securing a parking spot)

      📘

      Note

      This duration represents only the parking activity itself, not the time the vehicle remains parked while serving associated jobs.

    • vehicleTypeIds (optional): An array of vehicle type IDs that should use this specific parking duration. When specified, only vehicles matching these IDs will use this parking place. When omitted, the parking place with its corresponding duration and location serve as the default parking location and applies to all vehicles. You can designate only a single default parking location.

    • location (optional): An object with lat/lng coordinates. The parking behavior changes, depending whether or not you specify the parking location:

      • When you omit location, parking occurs at the job location.
      • When you specify location, parking occurs at these coordinates, separate from job locations. Multiple jobs can reference the same parking ID with coordinates. When they do, the vehicle visits the parking location and serves those jobs from there. A vehicle can visit the same parking location multiple times if needed.
      📘

      Important

      When using parking locations with explicit coordinates, you must configure the following in your vehicle shifts:

      1. Add stopConfiguration to specify the profile used to calculate walking distances between the parking spot and job locations.
      2. Ensure the profile referenced in stopConfiguration (for example, pedestrian) is also defined in the fleet.profiles array.

      Without this configuration, the API returns an error.

      For more information about stopConfiguration, see Cluster nearby stops.

      Example:

      "fleet": {
  "types": [
    {
      "id": "small_van",
      "profile": "car",
      "shifts": [
        {
          "start": { ... },
          "end": { ... },
          "stopConfiguration": {
            "profile": "pedestrian"
          }
        }
      ]
    }
  ],
  "profiles": [
    {
      "type": "car",
      "name": "car"
    },
    {
      "type": "pedestrian",
      "name": "pedestrian"
    }
  ]
}

Configuration limits:

  • Each parking can have up to 10 places with different durations. Multiple places may share the same location, but only single default place (a place without vehicleTypeIds) is allowed per location.
  • Job places can reference only one parking ID using the parkingIds array

The following snippet shows a sample shared.parking configuration:

"shared": {
  "parking": [
    {
      "id": "parking_downtown",
      "places": [
        {
          "duration": 90,
          "vehicleTypeIds": ["small_van_experienced"],
          "location": {
            "lat": 52.53184,
            "lng": 13.38462
          }
        },
        {
          "duration": 180,
          "location": {
            "lat": 52.53184,
            "lng": 13.38462
          }
        }
      ]
    },
    {
      "id": "parking_residential",
      "places": [
        {
          "duration": 45,
          "vehicleTypeIds": ["small_van_experienced"]
        },
        {
          "duration": 90
        }
      ]
    }
  ]
}

The configuration from the previous example demonstrates how parking durations can vary by both location and driver experience:

  • parking_downtown (with location coordinates): Vehicles park at the designated parking lot (52.53184, 13.38462) before serving downtown jobs. Experienced drivers (small_van_experienced) take 90 seconds to park, while standard drivers take 180 seconds.
  • parking_residential (without location coordinates): Vehicles park at each individual job location. Experienced drivers (small_van_experienced) take 45 seconds to park, while standard drivers take 90 seconds.

When a vehicle visits a job location with a parkingIds reference, the optimization algorithm evaluates all available parking places for that parking ID and automatically selects the most cost-effective option. This evaluation considers factors such as parking duration, walking distance (when parking occurs at designated coordinates), vehicle routing efficiency, and overall tour cost. This approach allows you to define multiple parking alternatives with different durations and locations, and the optimization algorithm automatically determines which option minimizes the total cost of the solution.

Job-specific park assignment

To assign jobs to specific parking spots, reference the parking IDs that you defined previously in job places by using the parkingIds array.

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

Considerations for duration and distance calculation when parking

Parking location routing: When using parking location coordinates, the service adds up the distance spent walking from the parking spot with a specific ID to serve all the jobs with the corresponding parking ID and then back to the parking spot as part of the statistic.intraStopDistance property value, summed up for all parking IDs.

Combined parking duration:

  • No parking location: The service adds up parking durations for all jobs and includes this total in the statistic.duration.times.stopping field of the solution. When multiple jobs at the same location reference the same parking without location coordinates, the API counts parking duration only once per trip, not for each job.
  • Parking location included: When jobs share a parking ID with specified coordinates, the stopping value equals the parking.places.duration counted once per parking visit, regardless of how many jobs use that parking location. If the vehicle must visit the same parking location multiple times, the parking duration applies to each visit. With multiple parking IDs that have coordinates, the stopping value is the sum of their durations across all visits.

Assignment order dependency: For jobs with multiple assignments where only some reference parkingIds, the service uses the first assignment in the sequence to determine parking behavior:

  • If the first assignment in the sequence does not reference parkingIds, the service ignores parking durations for all subsequent assignments in that job, even if specified, and the total parking duration for such a stop is always zero.
  • If the first assignment in the sequence references parkingIds, the service uses the parking duration from the first assignment for the entire stop, ignoring any parking durations specified in subsequent assignments.
  • When multiple jobs are assigned to the same location, only the parking duration from the first assignment of the first job is applied to the entire stop, regardless of parking durations specified in subsequent jobs at that location.

For a practical demonstration of these principles, see the sample use cases in the following sections.

Example #1: Urban delivery tours with experience-based parking efficiency

This example demonstrates job-specific parking duration working in a simplified mixed-fleet urban delivery scenario. The problem involves delivering packages across downtown and residential areas in Berlin, where parking conditions vary by job location and driver experience affects parking efficiency.

Problem setup

The delivery scenario includes:

  • Fleet: Three small vans with capacity for 4 packages each
    • small_van: Two standard delivery vans (2 vehicles available)
    • small_van_experienced: One van with experienced driver (1 vehicle available)
  • Job locations: Eight delivery stops across two areas
    • Downtown area: Jobs 1-4 (tighter parking, more time needed)
    • Residential area: Jobs 5-8 (easier parking, less time needed)
  • Parking constraints based on driver experience:
    • Downtown + experienced driver (small_van_experienced): 90 seconds
    • Downtown + standard driver (default): 180 seconds
    • Residential + experienced driver (small_van_experienced): 45 seconds
    • Residential + standard driver (default): 90 seconds
  • Service times: Each delivery requires 300 seconds (five minutes)
  • Job assignments:
    • Jobs 1-4 reference parking_downtown
    • Jobs 5-8 reference parking_residential

The following section provides the full problem JSON:

Click to expand/collapse the sample JSON
{
  "fleet": {
    "types": [
      {
        "id": "small_van",
        "profile": "car",
        "costs": {
          "fixed": 10.0,
          "distance": 0.001,
          "time": 0.002
        },
        "shifts": [
          {
            "start": {
              "time": "2024-06-24T06:00:00Z",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              }
            },
            "end": {
              "time": "2024-06-24T20:00:00Z",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              }
            }
          }
        ],
        "capacity": [4],
        "amount": 2
      },
      {
        "id": "small_van_experienced",
        "profile": "car",
        "costs": {
          "fixed": 10.0,
          "distance": 0.001,
          "time": 0.002
        },
        "shifts": [
          {
            "start": {
              "time": "2024-06-24T06:00:00Z",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              }
            },
            "end": {
              "time": "2024-06-24T20:00:00Z",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              }
            }
          }
        ],
        "capacity": [4],
        "amount": 1
      }
    ],
    "profiles": [
      {
        "type": "car",
        "name": "car"
      }
    ]
  },
  "plan": {
    "jobs": [
      {
        "id": "Job_1",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.531757,
                    "lng": 13.384426
                  },
                  "duration": 300,
                  "parkingIds": ["parking_downtown"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_2",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.532983,
                    "lng": 13.38787
                  },
                  "duration": 300,
                  "parkingIds": ["parking_downtown"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_3",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.532065,
                    "lng": 13.389091
                  },
                  "duration": 300,
                  "parkingIds": ["parking_downtown"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_4",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.530384,
                    "lng": 13.391224
                  },
                  "duration": 300,
                  "parkingIds": ["parking_downtown"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_5",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.530008,
                    "lng": 13.389562
                  },
                  "duration": 300,
                  "parkingIds": ["parking_residential"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_6",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.529496,
                    "lng": 13.385547
                  },
                  "duration": 300,
                  "parkingIds": ["parking_residential"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_7",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.528909,
                    "lng": 13.385381
                  },
                  "duration": 300,
                  "parkingIds": ["parking_residential"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_8",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.530533,
                    "lng": 13.383505
                  },
                  "duration": 300,
                  "parkingIds": ["parking_residential"]
                }
              ],
              "demand": [1]
            }
          ]
        }
      }
    ],
    "shared": {
      "parking": [
        {
          "id": "parking_downtown",
          "places": [
            {
              "duration": 90,
              "vehicleTypeIds": ["small_van_experienced"]
            },
            {
              "duration": 180
            }
          ]
        },
        {
          "id": "parking_residential",
          "places": [
            {
              "duration": 45,
              "vehicleTypeIds": ["small_van_experienced"]
            },
            {
              "duration": 90
            }
          ]
        }
      ]
    }
  },
  "configuration": {
    "experimentalFeatures": ["parkingIds"]
  }
}

Solution analysis

The following list provides the solution breakdown in terms of parking duration for each vehicle taking part in the tour:

Experienced Driver (small_van_experienced_1) tour:

  • Served: Job_8 (residential), Job_3, Job_2, Job_1 (downtown)
  • Stopping time: 315 seconds
    • 1 residential stop × 45 s = 45 s
    • 3 downtown stops × 90 s = 270 s

Standard Driver (small_van_2) tour:

  • Served: Job_6, Job_7, Job_5 (residential), Job_4 (downtown)
  • Stopping time: 450 seconds
    • 3 residential stops × 90 s = 270 s
    • 1 downtown stop × 180 s = 180 s

Total stopping time: 765 seconds (315 + 450), reflecting the combination of location-specific (downtown vs. residential) and vehicle-specific (experienced vs. standard driver) parking durations.

This demonstrates how experienced drivers can park more efficiently at both location types:

Location / Driver experienceExperienced DriverStandard Driver
Downtown90 s per stop180 s per stop (default)
Residential45 s per stop90 s per stop (default)

Parking duration in action:

Based on the solution for the previous problem, the following figure shows how parking duration creates a gap between vehicle arrival and service start for Job_8 and Job_6, depending on driver experience:

Tour summary highlighting parking durations for various stops

The experienced driver saves 45 seconds of parking time per residential stop compared to the standard driver (45 seconds versus 90 seconds).

The following section provides the full solution JSON:

Click to expand/collapse the sample JSON
{
  "statistic": {
    "cost": 30.481,
    "distance": 3003,
    "duration": 3739,
    "times": {
      "driving": 574,
      "serving": 2400,
      "waiting": 0,
      "stopping": 765,
      "break": 0
    }
  },
  "tours": [
    {
      "vehicleId": "small_van_experienced_1",
      "typeId": "small_van_experienced",
      "stops": [
        {
          "time": {
            "arrival": "2024-06-24T06:00:00Z",
            "departure": "2024-06-24T06:00:00Z"
          },
          "load": [4],
          "activities": [
            {
              "jobId": "departure",
              "type": "departure",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              },
              "time": {
                "start": "2024-06-24T06:00:00Z",
                "end": "2024-06-24T06:00:00Z"
              }
            }
          ],
          "location": {
            "lat": 52.53097,
            "lng": 13.38504
          },
          "distance": 0
        },
        {
          "time": {
            "arrival": "2024-06-24T06:00:14Z",
            "departure": "2024-06-24T06:05:59Z"
          },
          "load": [3],
          "activities": [
            {
              "jobId": "Job_8",
              "type": "delivery",
              "location": {
                "lat": 52.530533,
                "lng": 13.383505
              },
              "time": {
                "start": "2024-06-24T06:00:59Z",
                "end": "2024-06-24T06:05:59Z"
              }
            }
          ],
          "location": {
            "lat": 52.530533,
            "lng": 13.383505
          },
          "distance": 117
        },
        {
          "time": {
            "arrival": "2024-06-24T06:07:14Z",
            "departure": "2024-06-24T06:13:44Z"
          },
          "load": [2],
          "activities": [
            {
              "jobId": "Job_3",
              "type": "delivery",
              "location": {
                "lat": 52.532065,
                "lng": 13.389091
              },
              "time": {
                "start": "2024-06-24T06:08:44Z",
                "end": "2024-06-24T06:13:44Z"
              }
            }
          ],
          "location": {
            "lat": 52.532065,
            "lng": 13.389091
          },
          "distance": 629
        },
        {
          "time": {
            "arrival": "2024-06-24T06:14:01Z",
            "departure": "2024-06-24T06:20:31Z"
          },
          "load": [1],
          "activities": [
            {
              "jobId": "Job_2",
              "type": "delivery",
              "location": {
                "lat": 52.532983,
                "lng": 13.38787
              },
              "time": {
                "start": "2024-06-24T06:15:31Z",
                "end": "2024-06-24T06:20:31Z"
              }
            }
          ],
          "location": {
            "lat": 52.532983,
            "lng": 13.38787
          },
          "distance": 761
        },
        {
          "time": {
            "arrival": "2024-06-24T06:21:57Z",
            "departure": "2024-06-24T06:28:27Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "Job_1",
              "type": "delivery",
              "location": {
                "lat": 52.531757,
                "lng": 13.384426
              },
              "time": {
                "start": "2024-06-24T06:23:27Z",
                "end": "2024-06-24T06:28:27Z"
              }
            }
          ],
          "location": {
            "lat": 52.531757,
            "lng": 13.384426
          },
          "distance": 1120
        },
        {
          "time": {
            "arrival": "2024-06-24T06:28:49Z",
            "departure": "2024-06-24T06:28:49Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "arrival",
              "type": "arrival",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              },
              "time": {
                "start": "2024-06-24T06:28:49Z",
                "end": "2024-06-24T06:28:49Z"
              }
            }
          ],
          "location": {
            "lat": 52.53097,
            "lng": 13.38504
          },
          "distance": 1234
        }
      ],
      "statistic": {
        "cost": 14.692,
        "distance": 1234,
        "duration": 1729,
        "times": {
          "driving": 214,
          "serving": 1200,
          "waiting": 0,
          "stopping": 315,
          "break": 0
        }
      },
      "shiftIndex": 0
    },
    {
      "vehicleId": "small_van_2",
      "typeId": "small_van",
      "stops": [
        {
          "time": {
            "arrival": "2024-06-24T06:00:00Z",
            "departure": "2024-06-24T06:00:00Z"
          },
          "load": [4],
          "activities": [
            {
              "jobId": "departure",
              "type": "departure",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              },
              "time": {
                "start": "2024-06-24T06:00:00Z",
                "end": "2024-06-24T06:00:00Z"
              }
            }
          ],
          "location": {
            "lat": 52.53097,
            "lng": 13.38504
          },
          "distance": 0
        },
        {
          "time": {
            "arrival": "2024-06-24T06:01:08Z",
            "departure": "2024-06-24T06:07:38Z"
          },
          "load": [3],
          "activities": [
            {
              "jobId": "Job_6",
              "type": "delivery",
              "location": {
                "lat": 52.529496,
                "lng": 13.385547
              },
              "time": {
                "start": "2024-06-24T06:02:38Z",
                "end": "2024-06-24T06:07:38Z"
              }
            }
          ],
          "location": {
            "lat": 52.529496,
            "lng": 13.385547
          },
          "distance": 422
        },
        {
          "time": {
            "arrival": "2024-06-24T06:08:14Z",
            "departure": "2024-06-24T06:14:44Z"
          },
          "load": [2],
          "activities": [
            {
              "jobId": "Job_7",
              "type": "delivery",
              "location": {
                "lat": 52.528909,
                "lng": 13.385381
              },
              "time": {
                "start": "2024-06-24T06:09:44Z",
                "end": "2024-06-24T06:14:44Z"
              }
            }
          ],
          "location": {
            "lat": 52.528909,
            "lng": 13.385381
          },
          "distance": 550
        },
        {
          "time": {
            "arrival": "2024-06-24T06:15:57Z",
            "departure": "2024-06-24T06:22:27Z"
          },
          "load": [1],
          "activities": [
            {
              "jobId": "Job_5",
              "type": "delivery",
              "location": {
                "lat": 52.530008,
                "lng": 13.389562
              },
              "time": {
                "start": "2024-06-24T06:17:27Z",
                "end": "2024-06-24T06:22:27Z"
              }
            }
          ],
          "location": {
            "lat": 52.530008,
            "lng": 13.389562
          },
          "distance": 897
        },
        {
          "time": {
            "arrival": "2024-06-24T06:23:21Z",
            "departure": "2024-06-24T06:31:21Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "Job_4",
              "type": "delivery",
              "location": {
                "lat": 52.530384,
                "lng": 13.391224
              },
              "time": {
                "start": "2024-06-24T06:26:21Z",
                "end": "2024-06-24T06:31:21Z"
              }
            }
          ],
          "location": {
            "lat": 52.530384,
            "lng": 13.391224
          },
          "distance": 1107
        },
        {
          "time": {
            "arrival": "2024-06-24T06:32:58Z",
            "departure": "2024-06-24T06:32:58Z"
          },
          "load": [0],
          "activities": [
            {
              "jobId": "arrival",
              "type": "arrival",
              "location": {
                "lat": 52.53097,
                "lng": 13.38504
              },
              "time": {
                "start": "2024-06-24T06:32:58Z",
                "end": "2024-06-24T06:32:58Z"
              }
            }
          ],
          "location": {
            "lat": 52.53097,
            "lng": 13.38504
          },
          "distance": 1629
        }
      ],
      "statistic": {
        "cost": 15.585,
        "distance": 1629,
        "duration": 1978,
        "times": {
          "driving": 328,
          "serving": 1200,
          "waiting": 0,
          "stopping": 450,
          "break": 0
        }
      },
      "shiftIndex": 0
    }
  ]
}

Example #2: Selecting an optimal parking location with clustered delivery stops

This example demonstrates how the optimization algorithm automatically selects the most efficient parking location when multiple parking places share the same parking ID. The vehicle parks once at the optimal location, and the driver walks to serve all nearby deliveries. This approach is particularly effective when combined with the clusterNearby feature, which optimizes both the walking distance and the sequence of stops within the cluster.

Problem setup

The delivery scenario includes:

  • Fleet: One small delivery car with capacity for 30 packages
    • Vehicle type: vehicle_1
    • Profile: small_delivery_car (car)
    • Pedestrian profile: pedestrian (for walking between deliveries)
  • Job locations: Five delivery stops in downtown Phoenix, Arizona
    • All jobs (Job_1 through Job_5) reference the same parking ID: parking_downtown
    • Job locations clustered within approximately 100-150 meters of each other
  • Parking configuration: Two parking places with the same parking ID but different locations:
    • Parking place 1: Location (33.50972862, -112.069976), duration: 120 seconds
    • Parking place 2: Location (33.5088826144415, -112.07054302), duration: 240 seconds
  • Service times: Each delivery requires 300 seconds (five minutes)
  • Key configuration features:
    • stopConfiguration with pedestrian profile for calculating walking distances
    • maxIntraStopDistance: 600 meters (maximum walking distance allowed). When the cumulative walking distance from the parking location exceeds this limit, the optimization algorithm inserts a backToVehicle activity, requiring the courier to return to the parked vehicle before continuing to serve the remaining jobs.
    • clusterNearby feature to optimize stop clustering and walking routes

Important considerations:

When multiple parking places share the same parking ID, the optimization algorithm evaluates all available options and automatically selects the most cost-effective location based on:

  • Parking duration
  • Total walking distance to all associated job locations
  • Vehicle routing efficiency

In this example, even though parking place 1 has a shorter parking duration (120 s versus 240 s), the optimization algorithm must balance this against the total walking distance and service sequence efficiency.

Problem setup showing two parking locations with the same ID

The following section provides the full problem JSON:

Click to expand/collapse the sample JSON
{
  "fleet": {
    "types": [
      {
        "profile": "small_delivery_car",
        "amount": 1,
        "capacity": [30],
        "costs": {
          "time": 0.005,
          "distance": 0.0002,
          "fixed": 100
        },
        "id": "vehicle_1",
        "shifts": [
          {
            "start": {
              "location": {
                "lat": 33.51006,
                "lng": -112.07187
              },
              "time": "2026-07-22T06:00:00+02:00"
            },
            "end": {
              "location": {
                "lat": 33.51006,
                "lng": -112.07187
              },
              "time": "2026-07-22T21:00:00+02:00"
            },
            "stopConfiguration": {
              "profile": "pedestrian",
              "limits": {
                "maxIntraStopDistance": 600
              }
            }
          }
        ]
      }
    ],
    "profiles": [
      {
        "name": "small_delivery_car",
        "type": "car"
      },
      {
        "name": "pedestrian",
        "type": "pedestrian"
      }  
    ]
  },
  "plan": {
    "jobs": [
      {
        "id": "Job_1",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "duration": 300,
                  "parkingIds": ["parking_downtown"],
                  "location": {
                    "lat": 33.50999,
                    "lng": -112.07061
                  }
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_2",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "duration": 300,
                  "parkingIds": ["parking_downtown"],
                  "location": {
                    "lat": 33.5097,
                    "lng": -112.07032
                  }
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_3",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "duration": 300,
                  "parkingIds": ["parking_downtown"],
                  "location": {
                    "lat": 33.50951,
                    "lng": -112.07098
                  }
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_4",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "duration": 300,
                  "parkingIds": ["parking_downtown"],
                  "location": {
                    "lat": 33.50905,
                    "lng": -112.07093
                  }
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_5",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "duration": 300,
                  "parkingIds": ["parking_downtown"],
                  "location": {
                    "lat": 33.50892,
                    "lng": -112.07029
                  }
                }
              ],
              "demand": [1]
            }
          ]
        }
      }
    ],
    "shared": {
      "parking": [
        {
          "id": "parking_downtown",
          "places": [
            {
              "duration": 120,
              "location": {
                "lat": 33.50972862,
                "lng": -112.069976
              }
            },
            {
              "duration": 240,
              "location": {
                "lat": 33.5088826144415,
                "lng": -112.07054302
              }
            }
          ]
        }
      ]
    }
  },
  "configuration": {
    "experimentalFeatures": [
      "parkingIds",
      "clusterNearby"
    ]
  }
}

Solution analysis

The optimization algorithm selected parking place 1 (33.50972862, -112.069976) with a 120-second parking duration as the most efficient option. This location provides the best balance between parking time and walking distance to all five delivery locations.

Tour breakdown:

The vehicle completes the tour as follows:

  1. Departs from depot (33.51006, -112.07187) at 04:00:00Z
  2. Drives 274 meters to parking location (33.50972862, -112.069976)
  3. Parks once (duration: 120 seconds)
  4. Walks to serve all five jobs in optimized sequence:
    • Job_5 → Job_4 → Job_3 → Job_1 → Job_2
  5. Returns to parking location
  6. Drives 274 meters back to depot, arriving at 04:40:10Z

Walking optimization with clusterNearby:

The clusterNearby feature plays a crucial role in this solution by:

  • Optimizing the walking sequence: The jobs are served in an order that minimizes the total walking distance (Job_5 → Job_4 → Job_3 → Job_1 → Job_2), rather than a random sequence
  • Minimizing intra-stop distance: Total walking distance is 556 meters for all five deliveries
  • Balancing parking and walking costs: The optimization algorithm considers both the parking duration and the pedestrian travel times between clustered stops

Statistics breakdown:

MetricValueNotes
Total duration2,410 seconds (40 minutes, 10 seconds)
Driving time149 secondsVehicle travel on roads
Stopping time120 secondsParking duration (counted once, not 5 times)
Serving time1,500 seconds5 jobs × 300 seconds each
Intra-stop time641 secondsWalking time between jobs
Intra-stop distance556 metersTotal walking distance for all 5 deliveries
Driving distance548 metersDepot → parking → depot

Key insights:

  • The parking duration appears only once in the stopping time (120 seconds), not five times, because the vehicle is parked once and the driver walks to all job locations
  • The walking distance (556 meters) and walking time (641 seconds) are captured in intraStopDistance and intraStop time fields
  • The optimization algorithm chose parking place 1 (120 s) over parking place 2 (240 s), indicating that the shorter parking duration combined with acceptable walking distances resulted in a lower total cost
  • The clusterNearby feature ensures that the sequence of deliveries within the cluster is optimized to minimize walking distance
  • If the cumulative walking distance exceeds the maxIntraStopDistance limit (600 meters in this example), the solution would include a backToVehicle activity, splitting the cluster into multiple walking segments from the same parking location
Solution showing the selected parking location and optimized delivery sequence

The following section provides the full solution JSON:

Click to expand/collapse the sample JSON
{
  "statistic": {
    "cost": 112.1596,
    "distance": 548,
    "duration": 2410,
    "times": {
      "break": 0,
      "driving": 149,
      "serving": 1500,
      "stopping": 120,
      "waiting": 0,
      "intraStop": 641
    },
    "intraStopDistance": 556
  },
  "tours": [
    {
      "shiftIndex": 0,
      "statistic": {
        "cost": 112.1596,
        "distance": 548,
        "duration": 2410,
        "times": {
          "break": 0,
          "driving": 149,
          "serving": 1500,
          "stopping": 120,
          "waiting": 0,
          "intraStop": 641
        },
        "intraStopDistance": 556
      },
      "stops": [
        {
          "activities": [
            {
              "jobId": "departure",
              "type": "departure",
              "location": {
                "lat": 33.51006,
                "lng": -112.07187
              },
              "time": {
                "end": "2026-07-22T04:00:00Z",
                "start": "2026-07-22T04:00:00Z",
                "arrival": "2026-07-22T04:00:00Z"
              }
            }
          ],
          "load": [5],
          "time": {
            "arrival": "2026-07-22T04:00:00Z",
            "departure": "2026-07-22T04:00:00Z"
          },
          "distance": 0,
          "location": {
            "lat": 33.51006,
            "lng": -112.07187
          }
        },
        {
          "activities": [
            {
              "jobId": "Job_5",
              "type": "delivery",
              "location": {
                "lat": 33.50892,
                "lng": -112.07029
              },
              "time": {
                "end": "2026-07-22T04:10:14Z",
                "start": "2026-07-22T04:05:14Z",
                "arrival": "2026-07-22T04:05:14Z"
              }
            },
            {
              "jobId": "Job_4",
              "type": "delivery",
              "location": {
                "lat": 33.50905,
                "lng": -112.07093
              },
              "time": {
                "end": "2026-07-22T04:17:38Z",
                "start": "2026-07-22T04:12:38Z",
                "arrival": "2026-07-22T04:12:38Z"
              }
            },
            {
              "jobId": "Job_3",
              "type": "delivery",
              "location": {
                "lat": 33.50951,
                "lng": -112.07098
              },
              "time": {
                "end": "2026-07-22T04:24:07Z",
                "start": "2026-07-22T04:19:07Z",
                "arrival": "2026-07-22T04:19:07Z"
              }
            },
            {
              "jobId": "Job_1",
              "type": "delivery",
              "location": {
                "lat": 33.50999,
                "lng": -112.07061
              },
              "time": {
                "end": "2026-07-22T04:31:43Z",
                "start": "2026-07-22T04:26:43Z",
                "arrival": "2026-07-22T04:26:43Z"
              }
            },
            {
              "jobId": "Job_2",
              "type": "delivery",
              "location": {
                "lat": 33.5097,
                "lng": -112.07032
              },
              "time": {
                "end": "2026-07-22T04:38:36Z",
                "start": "2026-07-22T04:33:36Z",
                "arrival": "2026-07-22T04:33:36Z"
              }
            }
          ],
          "load": [0],
          "time": {
            "arrival": "2026-07-22T04:01:24Z",
            "departure": "2026-07-22T04:39:05Z"
          },
          "distance": 274,
          "intraStopDistance": 556,
          "location": {
            "lat": 33.50972862,
            "lng": -112.069976
          }
        },
        {
          "activities": [
            {
              "jobId": "arrival",
              "type": "arrival",
              "location": {
                "lat": 33.51006,
                "lng": -112.07187
              },
              "time": {
                "end": "2026-07-22T04:40:10Z",
                "start": "2026-07-22T04:40:10Z",
                "arrival": "2026-07-22T04:40:10Z"
              }
            }
          ],
          "load": [0],
          "time": {
            "arrival": "2026-07-22T04:40:10Z",
            "departure": "2026-07-22T04:40:10Z"
          },
          "distance": 548,
          "location": {
            "lat": 33.51006,
            "lng": -112.07187
          }
        }
      ],
      "typeId": "vehicle_1",
      "vehicleId": "vehicle_1_1"
    }
  ]
}

Next steps

Updated 12 days ago

Did this page help you?