Struct google_maps::directions::request::Request

pub struct Request<'a> { /* fields omitted */ }

Look at this Request struct for documentation on how to build your Directions API query. The methods implemented for this struct are what's used to build your request.

Methods

impl<'a> Request<'a>

pub fn build(&'a mut self) -> Result<&'a mut Request, Error>

Builds the query string for the Google Maps Directions API based on the input provided by the client.

Arguments:

This method accepts no arguments.

impl<'a> Request<'a>

pub fn execute(&'a mut self) -> Result<Response, Error>

Executes the query you've built.

Description:

My adventures in Rust became messy so I had to make this method. It wraps the .validate()?.build()?.get()? chain needed at the end of the builder pattern.

Arguments:

This method accepts no arguments.

impl<'a> Request<'a>

pub fn get(&mut self) -> Result<Response, Error>

Performs the HTTP get request and returns the response to the caller.

Arguments:

This method accepts no arguments.

impl<'a> Request<'a>

pub fn new(
    client_settings: &mut ClientSettings,
    origin: Location,
    destination: Location
) -> Request

Initializes the data structure for the builder pattern.

Arguments:

This method accepts no arguments.

impl<'a> Request<'a>

pub fn validate(&'a mut self) -> Result<&'a mut Request, Error>

Ensures the built query is valid. This function checks the combination of parameters to ensure that they make sense together and that Google Maps Directions API will accept them - i.e. it will not allow both a arrival time and departure time in the same query. This function does not check parameter values for validity - i.e. it will not ensure Polylines or Place ID's are valid and well-formed.

Arguments:

This method accepts no arguments.

impl<'a> Request<'a>

pub fn with_alternatives(&'a mut self, alternatives: bool) -> &'a mut Request

Specify whether service may provide more than one route alternative in the response.

Arguments:

• alternatives ‧ Whether more than one route should be in Google's response.

Description

If set to true, specifies that the Directions service may provide more than one route alternative in the response. Note that providing route alternatives may increase the response time from the server. This is only available for requests without intermediate waypoints.

Example:

• Allow more than one route in the response:

.with_alternatives(true)

impl<'a> Request<'a>

pub fn with_arrival_time(
    &'a mut self,
    arrival_time: NaiveDateTime
) -> &'a mut Request

Specifies the desired arrival time.

Arguments:

• arrival_time ‧ The time the passenger should arrive at their final destination by.

Description:

Specifies the desired time of arrival for transit directions. You can use either the .with_departure_time() or the .with_arrival_time() method, but not both together.

Example:

• Arriving by January 1, 2019 at 12:00:00 AM:

.with_arrival_time(NaiveDate::from_ymd(2019, 1, 1).and_hms(0, 00, 0))

impl<'a> Request<'a>

pub fn with_departure_time(
    &'a mut self,
    departure_time: DepartureTime
) -> &'a mut Request

Specifies the desired departure time.

Arguments:

• departure_time ‧ The soonest time the passenger intends to depart. May be "now" or a specified time.

Description

Specifies the desired time of departure. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). The departure time may be specified in two cases:

• For requests where the travel mode is transit: You can optionally use one of .with_departure_time() or .with_arrival_time() methods. If neither time is specified, the departure time defaults to now (that is, the departure time defaults to the current time).

• For requests where the travel mode is driving: You can specify the departure_time to receive a route and trip duration (response field: duration_in_traffic) that take traffic conditions into account. This option is only available if the request contains a valid API key, or a valid Google Maps Platform Premium Plan client ID and signature. The departure time must be set to the current time or some time in the future. It cannot be in the past.

• Note: If departure time is not specified, choice of route and duration are based on road network and average time-independent traffic conditions. Results for a given request may vary over time due to changes in the road network, updated average traffic conditions, and the distributed nature of the service. Results may also vary between nearly-equivalent routes at any time or frequency.

Examples:

• Departing now:

.with_departure_time(DepartureTime::Now)

• Departing on Tuesday February 22, 2022 at 1:00:00 PM:

.with_departure_time(DepartureTime::At(
    NaiveDate::from_ymd(2022, 2, 22).and_hms(13, 00, 0)
))

• Departing on Tuesday January 1, 2030 at 12:30:00 PM:

.with_departure_time(DepartureTime::At(
    NaiveDate::from_ymd(2030, 1, 1).and_hms(12, 30, 0)
))

impl<'a> Request<'a>

pub fn with_language(&'a mut self, language: Language) -> &'a mut Request

Specify the language in which to return results.

Arguments:

• language ‧ The language that Google's response should be presented in.

Description:

• See the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.

• If language is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header, or the native language of the domain from which the request is sent.

• The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.

• If a name is not available in the preferred language, the API uses the closest match.

• The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.

Example:

• Force language to French:

.with_language(Language::French)

impl<'a> Request<'a>

pub fn with_region(&'a mut self, region: Region) -> &'a mut Request

Specifies the region bias. There is a London in Canada and there is a London in England. By biasing the region, you help the directions service choose the London you intended.

Arguments

• region ‧ A country to bias your geocoding results to.

Description

Region Biasing

You can set the Directions service to return results from a specific region by using the region parameter. You may utilize any domain in which the main Google Maps application has launched driving directions.

For example, a directions request for "Toledo" to "Madrid" returns appropriate results when region is set to Region::Spain and "Toledo" is then interpreted as the Spanish city. A directions request for "Toledo" to "Madrid" sent without a region parameter does not return results, because "Toledo" is interpreted as the city in Ohio and not Spain.

Example:

• Bias region to Canada:

.with_region(Region::Canada)

impl<'a> Request<'a>

pub fn with_restriction(&'a mut self, restriction: Avoid) -> &'a mut Request

Specify a feature that routes should avoid.

Arguments

• restrictions ‧ A Vec containing a list of features that should be avoided when possible when calculating the route, such as ferries, highways, indoor steps, and/or tolls.

Description

Indicates that the calculated route(s) should avoid the indicated features. This parameter supports the following arguments:

• Avoid::Tolls indicates that the calculated route should avoid toll roads/bridges.

• Avoid::Highways indicates that the calculated route should avoid highways.

• Avoid::Ferries indicates that the calculated route should avoid ferries.

• Avoid::Indoor indicates that the calculated route should avoid indoor steps for walking and transit directions. Only requests that include an API key or a Google Maps Platform Premium Plan client ID will receive indoor steps by default.

Route Restrictions

Directions may be calculated that adhere to certain restrictions. Restrictions are indicated by use of the avoid parameter, and an argument to that parameter indicating the restriction to avoid.

It's possible to request a route that avoids any combination of tolls, highways and ferries by passing both restrictions.

Note: the addition of restrictions does not preclude routes that include the restricted feature; it simply biases the result to more favorable routes.

Examples:

• Only avoid highways:

.with_restriction(Avoid::Highways)

• Multiple restrictions may be stacked together. This example avoids tolls and ferries:

.with_restriction(Avoid::Tolls)
.with_restriction(Avoid::Ferries)

pub fn with_restrictions(
    &'a mut self,
    restrictions_slice: &[Avoid]
) -> &'a mut Request

Specify features that routes should avoid.

Example:

• Alternatively, multiple restrictions may be passed in a single method call by passing a Vec. This example avoids tolls and ferries:

.with_restrictions(vec![
    Avoid::Tolls,
    Avoid::Ferries,
])

impl<'a> Request<'a>

pub fn with_traffic_model(
    &'a mut self,
    traffic_model: TrafficModel
) -> &'a mut Request

Specifies the assumptions to use when calculating time in traffic.

Arguments

• traffic_model ‧ Which traffic model the directions service should use when calculating the route and duration in traffic - best guess, optimistic, or pessimistic?

Description

Specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration_in_traffic field in the response, which contains the predicted time in traffic based on historical averages. The traffic_model parameter may only be specified for driving directions where the request includes a departure_time, and only if the request includes an API key or a Google Maps Platform Premium Plan client ID. The available values for this parameter are:

• TrafficModel::BestGuess (default) indicates that the returned duration_in_traffic should be the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departure_time is to now.

• TrafficModel::Pessimistic indicates that the returned duration_in_traffic should be longer than the actual travel time on most days, though occasional days with particularly bad traffic conditions may exceed this value.

• TrafficModel::Optimistic indicates that the returned duration_in_traffic should be shorter than the actual travel time on most days, though occasional days with particularly good traffic conditions may be faster than this value.

The default value of BestGuess will give the most useful predictions for the vast majority of use cases. It is possible the BestGuess travel time prediction may be shorter than Optimistic, or alternatively, longer than Pessimistic, due to the way the BestGuess prediction model integrates live traffic information.

Example:

• Set traffic model to pessimistic:

.with_traffic_model(TrafficModel::Pessimistic)

impl<'a> Request<'a>

pub fn with_transit_mode(
    &'a mut self,
    transit_mode: TransitMode
) -> &'a mut Request

Specify the preferred mode of transit.

Arguments

• transit_modes ‧ The preference of the transit rider; what mode of transit should the directions service prioritize? Bus, Subway, Train, Tram, or Rail?

Description

Specifies one or more preferred modes of transit. This parameter may only be specified for transit directions, and only if the request includes an API key or a Google Maps Platform Premium Plan client ID. The parameter supports the following arguments:

• TransitMode::Bus indicates that the calculated route should prefer travel by bus.

• TransitMode::Subway indicates that the calculated route should prefer travel by subway.

• TransitMode::Train indicates that the calculated route should prefer travel by train.

• TransitMode::Tram indicates that the calculated route should prefer travel by tram and light rail.

• TransitMode::Rail indicates that the calculated route should prefer travel by train, tram, light rail, and subway. This is equivalent to TransitMode::Train|Tram|Subway.

Examples:

• Set preferred transit mode to rail:

.with_transit_mode((vec![TransitMode::Rail])

• Set preferred transit modes to bus and subway:

.with_transit_modes(vec![
    TransitMode::Bus,
    TransitMode::Subway
])

pub fn with_transit_modes(
    &'a mut self,
    transit_modes_slice: &[TransitMode]
) -> &'a mut Request

Specifies preferred modes of transit.

Example:

• Alternatively, multiple transit modes may be passed in a single method call by passing a Vec. This example sets preferred transit modes to bus and subway:

.with_transit_modes(vec![
    TransitMode::Bus,
    TransitMode::Subway,
])

impl<'a> Request<'a>

pub fn with_transit_route_preference(
    &'a mut self,
    transit_route_preference: TransitRoutePreference
) -> &'a mut Request

Specifies the preferences for transit routes.

Arguments

• transit_route_preference ‧ The preference of the transit rider; should the directions service try to reduce the amount of walking to reach the destination, or reduce the number of bus transfers?

Description

Specifies preferences for transit routes. Using this parameter, you can bias the options returned, rather than accepting the default best route chosen by the API. This parameter may only be specified for transit directions, and only if the request includes an API key or a Google Maps Platform Premium Plan client ID. The parameter supports the following arguments:

• TransitRoutePreference::LessWalking indicates that the calculated route should prefer limited amounts of walking.

• TransitRoutePreference::FewerTransfers indicates that the calculated route should prefer a limited number of transfers.

Example:

• Set transit route preference to fewer transfers:

.with_transit_route_preference(TransitRoutePreference::FewerTransfers)

impl<'a> Request<'a>

pub fn with_travel_mode(
    &'a mut self,
    travel_mode: TravelMode
) -> &'a mut Request

Specify the mode of transportation.

Arguments

• travel_mode ‧ The mode of transportation that directions should be calculated for. For example, transit directions or car driving directions.

Description

Travel Modes

When you calculate directions, you may specify the transportation mode to use. By default, directions are calculated as driving directions. The following travel modes are supported:

• TravelMode::Driving (default) indicates standard driving directions using the road network.

• TravelMode::Walking requests walking directions via pedestrian paths & sidewalks (where available).

• TravelMode::Bicycling requests bicycling directions via bicycle paths & preferred streets (where available).

• TravelMode::Transit requests directions via public transit routes (where available). If you set the travel mode to TravelMode::Transit, you can optionally use either with_departure_time() or with_arrival_time() methods. If neither time is specified, the departure time defaults to now (that is, the departure time defaults to the current time). You can also optionally use with_transit_mode() and/or with_transit_route_preference() methods.

Note: Both walking and bicycling directions may sometimes not include clear pedestrian or bicycling paths, so these directions will return warnings in the returned result which you must display to the user.

Example:

• Set travel mode to transit:

.with_travel_mode(TravelMode::Transit)

impl<'a> Request<'a>

pub fn with_unit_system(&'a mut self, unit_system: UnitSystem) -> &mut Request

Specifies the unit system to use when displaying results.

Arguments

• unit_system ‧ The measurement system the directions service should supply in the response, imperial or metric?

Description

Unit Systems

Directions results contain text within distance fields that may be displayed to the user to indicate the distance of a particular "step" of the route. By default, this text uses the unit system of the origin's country or region.

For example, a route from "Chicago, IL" to "Toronto, ONT" will display results in miles, while the reverse route will display results in kilometers. You may override this unit system by setting one explicitly within the request's unit_system parameter, passing one of the following values:

• UnitSystem::Metric specifies usage of the metric system. Textual distances are returned using kilometers and meters.

• UnitSystem::Imperial specifies usage of the Imperial (English) system. Textual distances are returned using miles and feet.

Note: this unit system setting only affects the text displayed within distance fields. The distance fields also contain values which are always expressed in meters.

Example:

• Force unit system to Metric:

.with_unit_system(UnitSystem::Metric)

impl<'a> Request<'a>

pub fn with_waypoint_optimization(
    &'a mut self,
    waypoint_optimization: bool
) -> &'a mut Request

Specifies whether the waypoint order should be optimized or not.

Arguments

• waypoint_optimization ‧ Specifies whether the waypoints should be rearranged into the most time-efficient order or not.

Description

Optimize your waypoints

By default, the Directions service calculates a route through the provided waypoints in their given order. Optionally, you may pass optimize:true as the first argument within the waypoints parameter to allow the Directions service to optimize the provided route by rearranging the waypoints in a more efficient order. (This optimization is an application of the traveling salesperson problem.) Travel time is the primary factor which is optimized, but other factors such as distance, number of turns and many more may be taken into account when deciding which route is the most efficient. All waypoints must be stopovers for the Directions service to optimize their route.

If you instruct the Directions service to optimize the order of its waypoints, their order will be returned in the waypoint_order field within the [routes](https://developers.google.com/maps/documentation/directions/intro#Routes) object. The waypoint_order field returns values which are zero-based.

The following example calculates a road journey from Adelaide, South Australia to each of South Australia's main wine regions using route optimization.

Example:

.with_waypoint_optimization(true)

impl<'a> Request<'a>

pub fn with_waypoint(&'a mut self, waypoint: Waypoint) -> &'a mut Request

Specify pass throughs or stopovers at intermediate locations.

Arguments

• waypoints ‧ Specifies intermediate locations to visit before arriving at the final destination.

Description

Specifies an array of intermediate locations to include along the route between the origin and destination points as pass through or stopover locations. Waypoints alter a route by directing it through the specified location(s). The API supports waypoints for these travel modes: driving, walking and bicycling; not transit. You can specify waypoints using the following values:

• Waypoint::Address: An explicit value pair.

• Waypoint::PlaceId: The unique value specific to a location. This value is only available only if the request includes an API key or Google Maps Platform Premium Plan client ID (ChIJGwVKWe5w44kRcr4b9E25).

• Waypoint::Address: Address string (Charlestown, Boston,MA)

• Waypoint::Polyline: Encoded polyline that can be specified by a set of any of the above. (lexeF{~wsZejrPjtye@:)

Waypoints

Caution: Requests using 10 or more waypoints, or waypoint optimization, are billed at a higher rate. Learn more about billing for Google Maps Platform products.

When calculating routes using the Directions API, you may specify waypoints to return a route that includes pass throughs or stopovers at intermediate locations. You can add waypoints to driving, walking or bicycling directions but not transit directions.

Specify locations in the waypoints parameter.

You can supply one or more locations in the form of a place ID, an address, or latitude/longitude coordinates. By default, the Directions service calculates a route using the waypoints in the order they are given. The precedence for parsing the value of the waypoint is place ID, latitude/longitude coordinates, then address.

• Waypoint::PlaceId If you pass a place ID, you must provide an API key or a Google Maps Platform Premium Plan client ID. You can retrieve place IDs from the Geocoding API and the Places API (including Place Autocomplete). For an example using place IDs from Place Autocomplete, see Place Autocomplete and Directions. For more about place IDs, see the Place ID overview.

• For efficiency and accuracy, use place ID's when possible. These ID's are uniquely explicit like a lat/lng value pair and provide geocoding benefits for routing such as access points and traffic variables. Unlike an address, ID's do not require the service to perform a search or an intermediate request for place details; therefore, performance is better.

• Waypoint::LatLng If you pass latitude/longitude coordinates, the values go directly to the front-end server to calculate directions without geocoding. The points are snapped to roads and might not provide the accuracy your app needs. Use coordinates when you are confident the values truly specify the points your app needs for routing without regard to possible access points or additional geocoding details.

• Waypoint::Address If you pass an address, the Directions service will geocode the string and convert it into latitude/longitude coordinates to calculate directions. If the address value is ambiguous, the value might evoke a search to disambiguate from similar addresses. For example, "1st Street" could be a complete value or a partial value for "1st street NE" or "1st St SE". This result may be different from that returned by the Geocoding API. You can avoid possible misinterpretations using place IDs. See troubleshooting the results of my route request.

Example:

• After departing from the origin location, stop for groceries at Sobeys before finally going to the destination location:

// Orléans Sobeys, 2276 Tenth Line Rd, Orléans, ON K4A 0X4
.with_waypoint(Waypoint::PlaceId(String::from("ChIJi5fWgmcSzkwRePJ_I9-xCRg")))

pub fn with_waypoints(
    &'a mut self,
    waypoints_slice: &[Waypoint]
) -> &'a mut Request

Example:

• After departing from the origin location; visit the Canadian Museum of Nature, Rideau Canal National Historic Site, intersection of Bank St & Queen Elizabeth Driveway, and then Patterson's Creek Park before finally going to the destination location:

.with_waypoints(vec![
    // Canadian Museum of Nature
    Waypoint::Address(String::from("240 McLeod St, Ottawa, ON K2P 2R1")),
    // Rideau Canal National Historic Site
    Waypoint::LatLng(LatLng::try_from(dec!(45.40453), dec!(-75.6821073))?),
    // Polyline to Bank St & Queen Elizabeth Driveway
    Waypoint::Polyline(String::from("}`ctGdm|lMfBdEfRsLdSbHfExT")),
    // Patterson's Creek Park
    Waypoint::PlaceId(String::from("ChIJyeH59bkFzkwRnPg4zYevwQk")),
])

Trait Implementations

impl<'a> Debug for Request<'a>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a> Eq for Request<'a>

impl<'a> Ord for Request<'a>

fn cmp(&self, other: &Request<'a>) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use] fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use] fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use] fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<'a> PartialEq<Request<'a>> for Request<'a>

fn eq(&self, other: &Request<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Request<'a>) -> bool

This method tests for !=.

impl<'a> PartialOrd<Request<'a>> for Request<'a>

fn partial_cmp(&self, other: &Request<'a>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Request<'a>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Request<'a>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Request<'a>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Request<'a>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> StructuralEq for Request<'a>

impl<'a> StructuralPartialEq for Request<'a>