Routing

Routing#

Note

Viewing documentation for the current version v1beta2.

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

ComputeTravelTimeMatrix#

rpc ComputeTravelTimeMatrix(ComputeTravelTimeMatrixRequest) stream ComputeTravelTimeMatrixResponse

Compute a matrix of travel times between locations in the given request. The response will be returned in a stream of chunks. We do not guarantee any specific order of the response chunks.

Since matrix computation can be computationally expensive, by default the API enforces a strict limit of at most 1000 matrix cells per second per account. This also means that requests for matrices larger than that will be rejected (additionally to the limits places on the request dimensions). Please reach out to the routing team if you want to use the matrix routing API with larger loads.

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
RESOURCE_EXHAUSTED: if the client currently exceeded its quota
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	The ID of a fleet (required). This fleet determines the geographic region, map data set and additional parameters used for routing. Coordinates outside the geographic region of the given fleet will fail to match.
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.

ComputeTravelTimeMatrixRequest#

A request for a matrix of travel times between multiple origins and destinations. The API currently allows computation of matrices with up to 1000x20000 locations (or 20000x1000), i.e. the larger dimension must be 20000 or less and the smaller 1000 or less.

Field	Type	Description
origins	repeated RoutingWaypoint	The set of origins to compute travel times from (required).
destinations	repeated RoutingWaypoint	The set of destinations to compute travel times to (required).
vehicle_configuration	VehicleConfiguration	Properties of the vehicle that should be routed (required).
fleet_id	string	The ID of a fleet (required). This fleet determines the geographic region, map data set and additional parameters used for routing. Coordinates outside the geographic region of the given fleet will fail to match.
optimization_criterion	optional OptimizationCriterion	The measure that is minimized during routing.

ComputeTravelTimeMatrixResponse#

A chunk of the response to the ComputeTravelTimeMatrix call.

Field	Type	Description
entries_offset	uint32	The start index of the entries contained in this chunk.
travel_times_seconds	uint32	(A chunk of) the matrix of travel times in seconds. The combined chunks yield a matrix in row-major order. Rows correspond to origins and columns correspond to destinations. That is, the travel time from the origin with index i to the destination with index j is stored at the travel time entry with index (i*num_destinations + j). A chunk contains the entries with indices `[entries_offset, entries_offset + len(travel_times_seconds))`.
violating_entries_indices	uint32	Lists all entry indices for which no violation-free route could be computed. That means the best route between the respective origin and destination violates one or more legal, physical, or user-defined restrictions. No route without violations could be found. Possible violations include, for example, passing through zones that forbid through traffic or using blocked roads. The travel time of the entry is still valid but the associated route likely cannot be driven.

Note that the indices in this list refer to the entries of this chunk. To obtain indices with respect to the complete matrix, the entries_offset must be added to each index. | no_route_found_entries_indices | uint32 | Lists all entry indices for which no travel time could be computed. If an entry is included here, its travel time is invalid and must not be used.

Note that the indices in this list refer to the entries of this chunk. To obtain indices with respect to the complete matrix, the entries_offset must be added to each index. | no_route_found_entries_reasons | repeated NoRouteFoundReason | Lists for every entry in no_route_found_entries_indices the reason that prevented the travel time 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	The ID of a fleet (required). This fleet determines the geographic region, map data set and additional parameters used for routing. Coordinates outside the geographic region of the given fleet will fail to match.
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.

Routing

Contents

Routing#

RoutingService#

ComputeRoute#

MatchPath#

ComputeTravelTimeMatrix#

Messages#

ComputeRouteRequest#

ComputeRouteResponse#

ComputeTravelTimeMatrixRequest#

ComputeTravelTimeMatrixResponse#

Leg#

LegOrLegWithViolations#

LegWithViolation#

Location#

MatchPathRequest#

MatchPathResponse#

Route#

RoutingWaypoint#

VehicleConfiguration#

Violation#

Enums#

NoRouteFoundReason#

OptimizationCriterion#

PathNotMatchedReason#

ViolationType#