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.
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 duration options in the
shared.parkingarray, each with a uniqueidandplacesthat contain duration and optional vehicle-specific assignments. - Job-specific parking assignments: Reference parking options in job places by using the
parkingIdsarray 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.
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 locationplaces(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)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 serve as a default and applies to all vehicles for which no specific place is defined.
Configuration limits:
- Each parking location can have up to 10 places with different durations
- Job places can reference only one parking ID using the
parkingIdsarray
The following snippet shows a sample shared.parking configuration:
"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
}
]
}
]
}The configuration from the previous example demonstrates how parking durations can vary by both location and driver experience:
parking_downtown: 90 seconds for experienced drivers (small_van_experienced), 180 seconds for standard drivers (any other vehicle id)parking_residential: 45 seconds for experienced drivers (small_van_experienced), 90 seconds for standard drivers (any other vehicle id)
When a vehicle visits a job location, the API matches the job's parkingIds reference with the vehicle's type ID to determine the appropriate parking duration. If no matching vehicleTypeIds is found, the API uses the first place without vehicleTypeIds as the default duration. This allows you to define specific durations for certain vehicle types while providing a fallback for all others.
Job-specific park assignment
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"
]
}
]Parking duration calculation
The HERE Tour Planning API calculates parking time as follows:
Combined parking duration: The service adds up parking durations for all jobs and includes this total in the statistic.duration.times.stopping field of the solution.
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: Urban delivery tours with experience-based parking efficiency
This example demonstrates location-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 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
- Downtown + experienced driver (
- Service times: Each delivery requires 300 seconds (five minutes)
- Job assignments:
- Jobs 1-4 reference
parking_downtown - Jobs 5-8 reference
parking_residential
- Jobs 1-4 reference
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 × 45s = 45s
- 3 downtown stops × 90s = 270s
Standard Driver (small_van_2) tour:
- Served:
Job_6,Job_7,Job_5(residential),Job_4(downtown) - Stopping time: 450 seconds
- 3 residential stops × 90s = 270s
- 1 downtown stop × 180s = 180s
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 experience | Experienced Driver | Standard Driver |
|---|---|---|
| Downtown | 90s per stop | 180s per stop (default) |
| Residential | 45s per stop | 90s 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:
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
}
]
}Next steps
For more information, see the HERE Tour Planning API Reference.
Updated 28 days ago