Optimize routes with side-of-street preferences
The sideOfStreetHint allows you to indicate which side of the street a driver should prefer for parking when visiting a specific location, potentially preventing unnecessary, inefficient, or even dangerous street crossings while making a stop. This is particularly useful in scenarios involving utility maintenance, postal deliveries, garbage collection, and so on, where it is both more practical and safe for vehicles to complete stops on one side of the street before moving to the other side.
This feature plays an important role when the service area (for example, a densely populated city center) contains such divided roads as boulevards with medians or multi-line highways. By using the sideOfStreetHint there, you can reduce the need for vehicles to make unnecessary turns or zigzag across traffic for minimal distance savings.
The following figure provides a visual representation of potential applications of the sideOfStreetHint feature while serving stops along a two-way street:
The solution on the left is showing a scenario that, while potentially more efficient, creates a sequence of stops that would require the vehicle to either stop on side of street opposite to the target job location or cut across the traffic going in the opposite direction (stops 2 and 5).
The solution on the right shows a sequence in which the vehicle serves jobs on the corresponding side of the street, without the need for crossing or zigzagging. This might be the preferred outcome for services like waste collection, utility, or postal services, and so on.
How side-of-street hints work
The sideOfStreetHint is part of the location object in job places array and contains the following components:
latandlngcoordinates that indicate a point on the preferred side of the street. This model provides unambiguous geographic references regardless of the travel direction.matchSideOfStreetparameter with the following options:always: This setting strictly enforces the side of street preference on all road types. For example, you can use this setting when you need the vehicle to always park on a specific side regardless of road conditions or you want to minimize potentially dangerous maneuvers even on small streets, at the cost of increased total tour distance or duration.onlyIfDivided: This setting applies the hint only on divided roads, that is, roads in which lanes are divided by painted lines or such physical barriers as grass, concrete, or painted islands. For example, you can use this setting if you want more routing flexibility while still avoiding crossing major traffic.
The following snippet shows a sample job configuration with a sideOfStreetHint:
{
"location": {
"lat": 52.53643,
"lng": 13.40718,
"sideOfStreetHint": {
"lat": 52.53643,
"lng": 13.40718,
"matchSideOfStreet": "always"
}
},
"duration": 300
}Note
Consider the following points when setting the
sideOfStreetHintfor your jobs:
- All jobs at same coordinates must have the same
sideOfStreetHintattribute- To ensure the optimization algorithm respects your side-of-street preference, configure the
sideOfStreetHintcoordinates using one of these approaches:
- Simple approach: Set the hint coordinates identical to the job
locationcoordinates- Precise approach: Calculate offset coordinates (10-20 meters perpendicular to the street) based on the street orientation
The simple approach works well for most scenarios, while the precise approach provides clearer side indication on complex road geometries.
Example: Garbage collection with side-of-street optimization
The following sections demonstrate a simplified scenario in which a garbage truck must collect bins along a divided boulevard in Berlin. In this scenario, the truck has to collect eight bins distributed on both sides of the street: four bins on the east side and four bins on the west side. Crossing a busy divided road while handling heavy bins poses a serious safety risk, so the optimal solution should minimize such crossings to protect the driver.
Problem without side-of-street hints
The starting problem defines bin pickup jobs without the sideOfStreetHint. Each job includes only a basic location (lat/lng) and a 300-second service duration. The optimization algorithm uses default tour objectives that prioritize minimizing unassigned jobs and tour costs. These objectives don't account for street-crossing safety, which might result in the vehicle zigzagging across the street to complete assignments.
See the following section for the full problem JSON:
Click to expand/collapse the sample JSON
{
"fleet": {
"types": [
{
"id": "garbage_truck",
"profile": "truck_profile",
"costs": {
"distance": 0.0002,
"time": 0.005,
"fixed": 100
},
"shifts": [
{
"start": {
"time": "2024-12-04T06:00:00Z",
"location": {
"lat": 52.53567,
"lng": 13.40641
}
},
"end": {
"time": "2024-12-04T14:00:00Z",
"location": {
"lat": 52.53567,
"lng": 13.40641
}
}
}
],
"capacity": [100],
"amount": 1
}
],
"profiles": [
{
"name": "truck_profile",
"type": "truck"
}
]
},
"plan": {
"jobs": [
{
"id": "east_1",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.536,
"lng": 13.40731
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_1",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53643,
"lng": 13.40718
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "east_2",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53668,
"lng": 13.40802
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_2",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53758,
"lng": 13.40839
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "east_3",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.5379,
"lng": 13.4093
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_3",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53902,
"lng": 13.40991
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_4",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53944,
"lng": 13.41036
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "east_4",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53967,
"lng": 13.41118
},
"duration": 300
}
],
"demand": [1]
}
]
}
}
]
}
}Solution without side-of-street hints
The resulting solution exhibits the following sequence of stops:
east_2 → east_4 → west_4 → west_3 → east_3 → west_2 → west_1 → east_1
While the vehicle must cross the divided road once to transition from the east side to the west side (at west_4), the optimizer then routes it back across the street two more times to serve individual stops (east_3 and east_1) before returning to complete the remaining west side collections. These unnecessary mid-route crossings create significant safety risks as the driver repeatedly navigates busy traffic while handling heavy bins. The following figure visualizes this inefficient solution, highlighting the zigzag pattern:
Click to expand/collapse the sample JSON
{
"statistic": {
"cost": 112.8096,
"distance": 1098,
"duration": 2518,
"times": {
"driving": 118,
"serving": 2400,
"waiting": 0,
"stopping": 0,
"break": 0
}
},
"tours": [
{
"vehicleId": "garbage_truck_1",
"typeId": "garbage_truck",
"stops": [
{
"time": {
"arrival": "2024-12-04T06:00:00Z",
"departure": "2024-12-04T06:00:00Z"
},
"load": [
0
],
"activities": [
{
"jobId": "departure",
"type": "departure",
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"time": {
"start": "2024-12-04T06:00:00Z",
"end": "2024-12-04T06:00:00Z"
}
}
],
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"distance": 0
},
{
"time": {
"arrival": "2024-12-04T06:00:16Z",
"departure": "2024-12-04T06:05:16Z"
},
"load": [
1
],
"activities": [
{
"jobId": "east_2",
"type": "pickup",
"location": {
"lat": 52.53668,
"lng": 13.40802
},
"time": {
"start": "2024-12-04T06:00:16Z",
"end": "2024-12-04T06:05:16Z"
}
}
],
"location": {
"lat": 52.53668,
"lng": 13.40802
},
"distance": 153
},
{
"time": {
"arrival": "2024-12-04T06:05:57Z",
"departure": "2024-12-04T06:10:57Z"
},
"load": [
2
],
"activities": [
{
"jobId": "east_4",
"type": "pickup",
"location": {
"lat": 52.53967,
"lng": 13.41118
},
"time": {
"start": "2024-12-04T06:05:57Z",
"end": "2024-12-04T06:10:57Z"
}
}
],
"location": {
"lat": 52.53967,
"lng": 13.41118
},
"distance": 549
},
{
"time": {
"arrival": "2024-12-04T06:11:03Z",
"departure": "2024-12-04T06:16:03Z"
},
"load": [
3
],
"activities": [
{
"jobId": "west_4",
"type": "pickup",
"location": {
"lat": 52.53944,
"lng": 13.41036
},
"time": {
"start": "2024-12-04T06:11:03Z",
"end": "2024-12-04T06:16:03Z"
}
}
],
"location": {
"lat": 52.53944,
"lng": 13.41036
},
"distance": 601
},
{
"time": {
"arrival": "2024-12-04T06:16:10Z",
"departure": "2024-12-04T06:21:10Z"
},
"load": [
4
],
"activities": [
{
"jobId": "west_3",
"type": "pickup",
"location": {
"lat": 52.53902,
"lng": 13.40991
},
"time": {
"start": "2024-12-04T06:16:10Z",
"end": "2024-12-04T06:21:10Z"
}
}
],
"location": {
"lat": 52.53902,
"lng": 13.40991
},
"distance": 657
},
{
"time": {
"arrival": "2024-12-04T06:21:24Z",
"departure": "2024-12-04T06:26:24Z"
},
"load": [
5
],
"activities": [
{
"jobId": "east_3",
"type": "pickup",
"location": {
"lat": 52.5379,
"lng": 13.4093
},
"time": {
"start": "2024-12-04T06:21:24Z",
"end": "2024-12-04T06:26:24Z"
}
}
],
"location": {
"lat": 52.5379,
"lng": 13.4093
},
"distance": 785
},
{
"time": {
"arrival": "2024-12-04T06:26:30Z",
"departure": "2024-12-04T06:31:30Z"
},
"load": [
6
],
"activities": [
{
"jobId": "west_2",
"type": "pickup",
"location": {
"lat": 52.53758,
"lng": 13.40839
},
"time": {
"start": "2024-12-04T06:26:30Z",
"end": "2024-12-04T06:31:30Z"
}
}
],
"location": {
"lat": 52.53758,
"lng": 13.40839
},
"distance": 848
},
{
"time": {
"arrival": "2024-12-04T06:31:45Z",
"departure": "2024-12-04T06:36:45Z"
},
"load": [
7
],
"activities": [
{
"jobId": "west_1",
"type": "pickup",
"location": {
"lat": 52.53643,
"lng": 13.40718
},
"time": {
"start": "2024-12-04T06:31:45Z",
"end": "2024-12-04T06:36:45Z"
}
}
],
"location": {
"lat": 52.53643,
"lng": 13.40718
},
"distance": 1000
},
{
"time": {
"arrival": "2024-12-04T06:36:49Z",
"departure": "2024-12-04T06:41:49Z"
},
"load": [
8
],
"activities": [
{
"jobId": "east_1",
"type": "pickup",
"location": {
"lat": 52.536,
"lng": 13.40731
},
"time": {
"start": "2024-12-04T06:36:49Z",
"end": "2024-12-04T06:41:49Z"
}
}
],
"location": {
"lat": 52.536,
"lng": 13.40731
},
"distance": 1035
},
{
"time": {
"arrival": "2024-12-04T06:41:58Z",
"departure": "2024-12-04T06:41:58Z"
},
"load": [
0
],
"activities": [
{
"jobId": "arrival",
"type": "arrival",
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"time": {
"start": "2024-12-04T06:41:58Z",
"end": "2024-12-04T06:41:58Z"
}
}
],
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"distance": 1098
}
],
"statistic": {
"cost": 112.8096,
"distance": 1098,
"duration": 2518,
"times": {
"driving": 118,
"serving": 2400,
"waiting": 0,
"stopping": 0,
"break": 0
}
},
"shiftIndex": 0
}
]
}Problem with side-of-street hints
In this version, the only difference from the previous problem is that each job contains a sideOfStreetHint whose coordinates are equal to the job location coordinates. The matchSideOfStreet parameter is set to always for strict enforcement on all road types.
See the following section for the full problem JSON:
Click to expand/collapse the sample JSON
{
"fleet": {
"types": [
{
"id": "garbage_truck",
"profile": "truck_profile",
"costs": {
"distance": 0.0002,
"time": 0.005,
"fixed": 100
},
"shifts": [
{
"start": {
"time": "2024-12-04T06:00:00Z",
"location": {
"lat": 52.53567,
"lng": 13.40641
}
},
"end": {
"time": "2024-12-04T14:00:00Z",
"location": {
"lat": 52.53567,
"lng": 13.40641
}
}
}
],
"capacity": [100],
"amount": 1
}
],
"profiles": [
{
"name": "truck_profile",
"type": "truck"
}
]
},
"plan": {
"jobs": [
{
"id": "east_1",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.536,
"lng": 13.40731,
"sideOfStreetHint": {
"lat": 52.536,
"lng": 13.40731,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_1",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53643,
"lng": 13.40718,
"sideOfStreetHint": {
"lat": 52.53643,
"lng": 13.40718,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "east_2",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53668,
"lng": 13.40802,
"sideOfStreetHint": {
"lat": 52.53668,
"lng": 13.40802,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_2",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53758,
"lng": 13.40839,
"sideOfStreetHint": {
"lat": 52.53758,
"lng": 13.40839,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "east_3",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.5379,
"lng": 13.4093,
"sideOfStreetHint": {
"lat": 52.5379,
"lng": 13.4093,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_3",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53902,
"lng": 13.40991,
"sideOfStreetHint": {
"lat": 52.53902,
"lng": 13.40991,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "west_4",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53944,
"lng": 13.41036,
"sideOfStreetHint": {
"lat": 52.53944,
"lng": 13.41036,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
},
{
"id": "east_4",
"tasks": {
"pickups": [
{
"places": [
{
"location": {
"lat": 52.53967,
"lng": 13.41118,
"sideOfStreetHint": {
"lat": 52.53967,
"lng": 13.41118,
"matchSideOfStreet": "always"
}
},
"duration": 300
}
],
"demand": [1]
}
]
}
}
]
}
}Solution with side-of-street hints
In this case, the route is much more efficient from the service point of view as the vehicle completes one side of the street then the other in the following sequence:
east_1 → east_2 → east_3 → east_4 → (turns around) → west_4 → west_3 → west_2 → west_1
The following figure provides a visual breakdown of the tour:
As the solution demonstrates, the tour distance increased by 400m compared with the previous solution (from 1100 m to 1500 m). The tour duration also increased by 143 seconds (from 2518 s to 2661 s), and the total cost increased from 112.81 to 113.60. In this case, the slightly higher cost, longer distance, and additional time are outweighed by dramatically improved safety.
See the following section for the full solution JSON:
Click to expand/collapse the sample JSON
{
"statistic": {
"cost": 113.60499999999999,
"distance": 1500,
"duration": 2661,
"times": {
"driving": 261,
"serving": 2400,
"waiting": 0,
"stopping": 0,
"break": 0
}
},
"tours": [
{
"vehicleId": "garbage_truck_1",
"typeId": "garbage_truck",
"stops": [
{
"time": {
"arrival": "2024-12-04T06:00:00Z",
"departure": "2024-12-04T06:00:00Z"
},
"load": [
0
],
"activities": [
{
"jobId": "departure",
"type": "departure",
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"time": {
"start": "2024-12-04T06:00:00Z",
"end": "2024-12-04T06:00:00Z"
}
}
],
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"distance": 0
},
{
"time": {
"arrival": "2024-12-04T06:00:07Z",
"departure": "2024-12-04T06:05:07Z"
},
"load": [
1
],
"activities": [
{
"jobId": "east_1",
"type": "pickup",
"location": {
"lat": 52.536,
"lng": 13.40731
},
"time": {
"start": "2024-12-04T06:00:07Z",
"end": "2024-12-04T06:05:07Z"
}
}
],
"location": {
"lat": 52.536,
"lng": 13.40731
},
"distance": 63
},
{
"time": {
"arrival": "2024-12-04T06:05:16Z",
"departure": "2024-12-04T06:10:16Z"
},
"load": [
2
],
"activities": [
{
"jobId": "east_2",
"type": "pickup",
"location": {
"lat": 52.53668,
"lng": 13.40802
},
"time": {
"start": "2024-12-04T06:05:16Z",
"end": "2024-12-04T06:10:16Z"
}
}
],
"location": {
"lat": 52.53668,
"lng": 13.40802
},
"distance": 153
},
{
"time": {
"arrival": "2024-12-04T06:10:32Z",
"departure": "2024-12-04T06:15:32Z"
},
"load": [
3
],
"activities": [
{
"jobId": "east_3",
"type": "pickup",
"location": {
"lat": 52.5379,
"lng": 13.4093
},
"time": {
"start": "2024-12-04T06:10:32Z",
"end": "2024-12-04T06:15:32Z"
}
}
],
"location": {
"lat": 52.5379,
"lng": 13.4093
},
"distance": 313
},
{
"time": {
"arrival": "2024-12-04T06:15:58Z",
"departure": "2024-12-04T06:20:58Z"
},
"load": [
4
],
"activities": [
{
"jobId": "east_4",
"type": "pickup",
"location": {
"lat": 52.53967,
"lng": 13.41118
},
"time": {
"start": "2024-12-04T06:15:58Z",
"end": "2024-12-04T06:20:58Z"
}
}
],
"location": {
"lat": 52.53967,
"lng": 13.41118
},
"distance": 549
},
{
"time": {
"arrival": "2024-12-04T06:23:27Z",
"departure": "2024-12-04T06:28:27Z"
},
"load": [
5
],
"activities": [
{
"jobId": "west_4",
"type": "pickup",
"location": {
"lat": 52.53944,
"lng": 13.41036
},
"time": {
"start": "2024-12-04T06:23:27Z",
"end": "2024-12-04T06:28:27Z"
}
}
],
"location": {
"lat": 52.53944,
"lng": 13.41036
},
"distance": 1003
},
{
"time": {
"arrival": "2024-12-04T06:28:34Z",
"departure": "2024-12-04T06:33:34Z"
},
"load": [
6
],
"activities": [
{
"jobId": "west_3",
"type": "pickup",
"location": {
"lat": 52.53902,
"lng": 13.40991
},
"time": {
"start": "2024-12-04T06:28:34Z",
"end": "2024-12-04T06:33:34Z"
}
}
],
"location": {
"lat": 52.53902,
"lng": 13.40991
},
"distance": 1059
},
{
"time": {
"arrival": "2024-12-04T06:33:53Z",
"departure": "2024-12-04T06:38:53Z"
},
"load": [
7
],
"activities": [
{
"jobId": "west_2",
"type": "pickup",
"location": {
"lat": 52.53758,
"lng": 13.40839
},
"time": {
"start": "2024-12-04T06:33:53Z",
"end": "2024-12-04T06:38:53Z"
}
}
],
"location": {
"lat": 52.53758,
"lng": 13.40839
},
"distance": 1250
},
{
"time": {
"arrival": "2024-12-04T06:39:08Z",
"departure": "2024-12-04T06:44:08Z"
},
"load": [
8
],
"activities": [
{
"jobId": "west_1",
"type": "pickup",
"location": {
"lat": 52.53643,
"lng": 13.40718
},
"time": {
"start": "2024-12-04T06:39:08Z",
"end": "2024-12-04T06:44:08Z"
}
}
],
"location": {
"lat": 52.53643,
"lng": 13.40718
},
"distance": 1402
},
{
"time": {
"arrival": "2024-12-04T06:44:21Z",
"departure": "2024-12-04T06:44:21Z"
},
"load": [
0
],
"activities": [
{
"jobId": "arrival",
"type": "arrival",
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"time": {
"start": "2024-12-04T06:44:21Z",
"end": "2024-12-04T06:44:21Z"
}
}
],
"location": {
"lat": 52.53567,
"lng": 13.40641
},
"distance": 1500
}
],
"statistic": {
"cost": 113.60499999999999,
"distance": 1500,
"duration": 2661,
"times": {
"driving": 261,
"serving": 2400,
"waiting": 0,
"stopping": 0,
"break": 0
}
},
"shiftIndex": 0
}
]
}Next steps
- For more information about the
sideOfStreetHintschema details, see the API Reference. - For another use case involving waste management, see Plan efficient routes for waste management fleets.
- For steps on how to visualize tours on a map, see Obtain route polylines for the tour.
Updated 28 days ago