Routing

Routing#

Note

Viewing documentation for the current version v1beta2.

To switch to an older version use the following links:

v1beta1

The required Protobuf definitions can be downloaded here:

moia/fleet/routing/v1beta2/routing.proto

RoutingService#

The RoutingService provides point-to-point routing for vehicles of a fleet.

ComputeRoute#

rpc ComputeRoute(ComputeRouteRequest) ComputeRouteResponse

Compute a route for the given request.

Potential Errors:

INVALID_ARGUMENT: if the incoming request has missing or invalid fields
PERMISSION_DENIED: if the client is not authorized to operate the given fleet
INTERNAL: internal error occurred

MatchPath#

rpc MatchPath(MatchPathRequest) MatchPathResponse

Match a path to the road network and obtain a corresponding route.

Potential Errors:

INVALID_ARGUMENT: if the incoming request has missing or invalid fields
PERMISSION_DENIED: if the client is not authorized to operate the given fleet
INTERNAL: internal error occurred

Messages#

ComputeRouteRequest#

A request for a route that traverses two or more waypoints.

Field	Type	Description
origin	RoutingWaypoint	The origin of the route (required).
destination	RoutingWaypoint	The destination of the route (required).
via	repeated RoutingWaypoint	Zero or more via waypoints that must be traversed in the given order. The API currently allows at most 100 via points.
vehicle_configuration	VehicleConfiguration	Properties of the vehicle that should be routed (required).
fleet_id	string	Each fleet may be associated with different routing parameters. This fleet_id is used to identify the fleet (required).
optimization_criterion	optional OptimizationCriterion	The measure that is minimized during routing.

ComputeRouteResponse#

A response to a ComputeRoute request.

Field	Type	Description
oneof content.route	Route	The route that traverses the requested waypoints.
oneof content.no_route_found	NoRouteFoundReason	The reason that prevented a route from being computed.

Leg#

A leg represents the part of a route between two consecutive waypoints and contains the coordinates, travel time and length of that part.

Field	Type	Description
travel_time_seconds	uint32	The time to traverse the leg in seconds.
length_meters	uint32	The length of the leg in meters.
geometry	repeated Location	A polyline that describes the geometry of the leg.

LegOrLegWithViolations#

This message is a container for leg data. It may consist either of a plain leg or alternatively, of a leg with violations. The service only responds with a leg with violations if no alternative route without violations exists. A leg with violations means that a route could be computed but it may be problematic and must be carefully considered in the context of the service consumer’s use case. Most violations indicate that it is illegal or impossible to drive a leg according to our routing data. Consider the ViolationType of the respective violations for more details on the severity of the problem.

Field	Type	Description
oneof content.leg	Leg	An unproblematic route leg.
oneof content.leg_with_violation	LegWithViolation	A route leg with violations. In this case, consumers of the routing service must carefully evaluate if the leg is usable for their purposes.

LegWithViolation#

A route leg that violates routing restrictions.

Field	Type	Description
leg	Leg	The route leg.
violations	repeated Violation	Restrictions violated by the leg.

Location#

A geographic coordinate.

Field	Type	Description
latitude	double	The latitude in degrees. [-90.0, +90.0].
longitude	double	The longitude in degrees. [-180.0, +180.0].

MatchPathRequest#

A request to match a path to the road network and obtain a corresponding route.

Field	Type	Description
fleet_id	string	Each fleet may be associated with different routing parameters. This fleet_id is used to identify the fleet (required).
path	repeated Location	A polyline that describes the path. The polyline must contain at least two locations (required).
vehicle_configuration	VehicleConfiguration	Properties of the vehicle that is targeted (required).

MatchPathResponse#

A response to a MatchPath request.

Field	Type	Description
oneof content.leg	LegOrLegWithViolations	The route that best corresponds to the provided path. Since it will always consist of exactly one section, we return a single `LegOrLegWithViolations` instead of a `Route`.
oneof content.path_not_matched_reason	PathNotMatchedReason	The reason that prevented a path from being matched.

Route#

A route from origin to destination traversing all given via locations (if any) in the specified order. It consists of one or more legs, each connecting two consecutive waypoints.

Field	Type	Description
legs	repeated LegOrLegWithViolations	The route sections that make up the route.

RoutingWaypoint#

A location that a route must traverse.

Field	Type	Description
latitude	double	The latitude in degrees. [-90.0, +90.0].
longitude	double	The longitude in degrees. [-180.0, +180.0].
heading	double	The horizontal direction in degrees, measured clockwise from north. [0.0-360.0°, 0.0° = facing north, 180.0° = facing south]

VehicleConfiguration#

Properties of a vehicle.

Field	Type	Description
self_driving	bool	Whether the vehicle is an autonomous vehicle.

Violation#

A violation indicates an issue with a route leg. While a route could be computed, the leg violates a routing restriction.

Field	Type	Description
violation_type	ViolationType	Describes the kind of underlying problem.
start_index	uint32	The index in the leg’s polyline at which the geometry of this violation starts.
coordinates_count	uint32	The number of successive coordinates making up the geometry of this violation. A zero would indicate that a violation has no geometry, a one that it consists of a singular point.

Enums#

NoRouteFoundReason#

An issue that prevented a route from being computed.

Name	Number	Description
NO_ROUTE_FOUND_REASON_UNSPECIFIED	0	A special value to indicate that a field is not set.
NO_ROUTE_FOUND_REASON_COULD_NOT_MATCH_WAYPOINT	1	A waypoint could not be matched to the road network, i.e. our map data contains no usable road within reasonable distance of the location for the given vehicle configuration.
NO_ROUTE_FOUND_REASON_COULD_NOT_REACH_WAYPOINT	2	A waypoint was not reachable from the preceding waypoint.

OptimizationCriterion#

The optimization criterion defines if travel time or distance is minimized during routing. Note that the result may not be the route with the strictly minimal value for the criterion as the service tries to avoid certain problematic route features such as U-turns or driving through inconvenient side roads etc.

Name	Number	Description
OPTIMIZATION_CRITERION_UNSPECIFIED	0	A special value to indicate that a field is not set.
OPTIMIZATION_CRITERION_TIME	1	Travel time is used as the main objective to be minimized during routing. Used by default when nothing else is specified.
OPTIMIZATION_CRITERION_DISTANCE	2	Driving distance is used as the main objective to be minimized during routing.

PathNotMatchedReason#

An issue that prevented a path from being matched.

Name	Number	Description
PATH_NOT_MATCHED_REASON_UNSPECIFIED	0	A special value to indicate that a field is not set.
PATH_NOT_MATCHED_REASON_COULD_NOT_MATCH_PATH	1	For the given vehicle configuration, our map data does not contain a path which stays within reasonable distance to the provided geometry.

ViolationType#

A ViolationType describes the kind of problem of a specific violation.

Name	Number	Description
VIOLATION_TYPE_UNSPECIFIED	0	A special value to indicate that a field is not set.
VIOLATION_TYPE_WRONG_DIRECTION_AT_ORIGIN	1	The leg departs at the origin in a different direction than requested.
VIOLATION_TYPE_WRONG_DIRECTION_AT_DESTINATION	2	The leg arrives at the destination in a different direction than requested.
VIOLATION_TYPE_INTERMEDIATE_LOCAL_ZONE_USED	3	The leg passes through a zone that forbids through traffic.
VIOLATION_TYPE_BLOCKED_ROAD_USED	4	The leg uses one or more blocked roads.
VIOLATION_TYPE_TIME_DEPENDENT_RESTRICTION_VIOLATED	5	The leg uses a road where driving is disallowed at the current time.
VIOLATION_TYPE_ROAD_FORBIDDEN_FOR_VEHICLE_CONFIGURATION_USED	6	The leg contains roads which cannot be driven with a vehicle of the specified configuration.
VIOLATION_TYPE_FORBIDDEN_TURN_USED	7	The leg contains a turn which is illegal (or impossible) to take.
VIOLATION_TYPE_TURN_FORBIDDEN_FOR_VEHICLE_CONFIGURATION_USED	8	The leg contains a turn which cannot be driven with a vehicle of the specified configuration.