Struct ForwardRequest

pub struct ForwardRequest<'r> { /* private fields */ }

Look at this Request struct for documentation on how to build your Geocoding API query. The methods implemented for this struct are what’s used to build your request. Forward geocoding looks up a longitude & latitude coordinates from a street address.

Implementations

impl<'r> ForwardRequest<'r>

pub fn build(&'r mut self) -> Result<&'r mut Self, Error>

👎Deprecated since 3.8.0: try using the query_string method instead

Builds the URL query string for the HTTP GET request.

Arguments

This method accepts no arguments.

Notes

• The query string is the part of the URL after the ? question mark. For example, in the URL https://example.com/over/there?name=ferret the query string is name=ferret

• The build method has been removed. It would store the generated query string inside of the request structure.

  This way, the same query string would only have to be generated once and could be used for any subsequent retries. This increased implementation complexity but had very performance little benefit. It has been removed.

  If you want to generate a query string (without the preceding URL), try the query_string method.

impl<'a> ForwardRequest<'a>

pub const fn new(client: &'a Client) -> Self

Initializes the builder pattern for a Geolocation API query with the required, non-optional parameters.

Arguments

• client ‧ Your application’s Google Maps API client struct.

impl ForwardRequest<'_>

pub fn with_address(self, address: impl Into<String>) -> Self

Specifies the street address to geocode.

Arguments

• address - The street address that you want to geocode, in the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers hould be avoided. Please refer to the FAQ for additional guidance.

Example

.with_address(String::from(
    "1313 Disneyland Dr, Anaheim, CA 92802, United States"
))

impl ForwardRequest<'_>

pub fn with_bounds(self, bounds: impl Into<Bounds>) -> Self

Specifies a bounding box for biasing results.

Arguments

• bounds - The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder.

Description

Viewport Biasing

In a Geocoding request, you can instruct the Geocoding service to prefer results within a given viewport (expressed as a bounding box). You do so within the request URL by setting the bounds parameter. Note that biasing only prefers results within the bounds; if more relevant results exist outside of these bounds, they may be included.

The bounds parameter defines the latitude/longitude coordinates of the southwest and northeast corners of this bounding box.

For example, a geocode for “Winnetka” generally returns this suburb of Chicago. However, adding a bounds argument defining a bounding box for the San Fernando Valley of Los Angeles results in this geocode returning the neighborhood named “Winnetka” in that location.

Example

• Specify bounding box for search area:

.with_bounds(Bounds {
    southwest: LatLng::try_from_dec(dec!(51.503_111_7), dec!(-0.129_150_3))?,
    northeast: LatLng::try_from_dec(dec!(51.503_440_5), dec!(-0.126_003_2))?,
})

impl ForwardRequest<'_>

pub fn with_component(self, component: impl Into<Component>) -> Self

Restricts the results from the geocoder to the specified component type(s).

Arguments

• component - A single component filter of Component type.

Description

Component Filtering

In a Geocoding response, the Geocoding API can return address results restricted to a specific area. You can specify the restriction using the components filter. Filter values support the same methods of spelling correction and partial matching as other Geocoding requests. If the geocoder finds a partial match for a component filter, the response will contain a partial_match field.

The components that can be filtered include:

• Component::Route matches the long or short name of a route.

• Component::Locality matches against locality and sublocality types.

• Component::AdministrativeArea matches all the administrative_area levels.

Notes about component filtering:

• If the request contains multiple component filters, the API evaluates them as an AND, not an OR. For example, if the request includes multiple countries components=country:GB|country:AU, the API looks for locations where country=GB AND country=AU, and returns ZERO_RESULTS.

• Results are consistent with Google Maps, which occasionally yields unexpected ZERO_RESULTS responses. Using Place Autocomplete may provide better results in some use cases. To learn more, see this FAQ.

• For each address component, either specify it in the address parameter or in a components filter, but not both. Specifying the same values in both may result in ZERO_RESULTS.

Examples:

• A single component filter. This example restricts results to Toronto:

.with_component(GeocodingComponent::Locality(String::from("Toronto")))

• Multiple component filters may be stacked together. This example restricts results to a street in a city:

.with_component(GeocodingComponent::Route(String::from("Downing Street")))
.with_component(GeocodingComponent::Locality(String::from("London")))

pub fn with_components<C, O>(self, components: C) -> Self

where C: IntoIterator<Item = O>, O: Into<Component>,

Restricts the results from the geocoder to the specified component type(s).

Example:

• Alternatively, multiple component filters may be passed in a single method call by passing a slice. This example restricts results to a street in a city:

.with_components(&[
    GeocodingComponent::Route(String::from("Downing Street")),
    GeocodingComponent::Locality(String::from("London")),
])

Generics

This method uses generics to improve ergonomics. The C generic is intended to represent any collection that can be iterated over, and the O generic is for any type that can be converted to the Component type.

impl ForwardRequest<'_>

pub fn with_language(self, language: impl Into<Language>) -> Self

Specifies the language in which to return results.

Arguments

• language - The language in which to return results.

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 geocoder 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 geocoder 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 geocoder 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 and square respectively in Hungarian.

Example

• Set language for result:

.with_language(Language::French)

impl ForwardRequest<'_>

pub fn with_place_id(self, place_id: impl Into<String>) -> Self

Specifies the place id to geocode.

Arguments

• place_id - TThe place ID of the place for which you wish to obtain the human-readable address. The place ID is a unique identifier that can be used with other Google APIs. For example, you can use the placeID returned by the Roads API to get the address for a snapped point. For more information about place IDs, see the place ID overview.

Example

.with_place_id(
    "ChIJd8BlQ2BZwokRAFUEcm_qrcA"
)

impl ForwardRequest<'_>

pub fn with_region(self, region: impl Into<Region>) -> Self

Specifies the region bias.

Arguments

• region ‧ The region to prefer in search results. This parameter will only influence, not fully restrict, results from the geocoder.

Description

Region Biasing

In a Geocoding request, you can instruct the Geocoding service to return results biased to a particular region by using the region parameter.

Geocoding results can be biased for every domain in which the main Google Maps application is officially launched. Note that biasing only prefers results for a specific domain; if more relevant results exist outside of this domain, they may be included.

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 ForwardRequest<'_>

pub async fn execute(self) -> Result<Response, Error>

Executes the Google Maps Geocoding API forward request.

Description

This method will:

1. Validate the request struct that has been built,

2. Build a URL and query string for an HTTP GET request,

3. Perform the HTTP GET request using the reqwest crate.

Arguments

This method accepts no arguments.

Errors

This method can fail if:

• This can fail if the request struct fails validation. For example, parameters in the request conflict with one another, or the request parameters are set in a way that’s incompatible.

  For example, Google Maps Directions API cannot calculate alternative routes if waypoints have been set. This will cause a validation failure.

• The HTTP client cannot make a connection to the Google Maps API server, or successfully send the request or receive the resposne over the network.

• The Google Maps API server returns an unexpected response, or data in a format that’s not expected.

impl ForwardRequest<'_>

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

👎Deprecated since 3.8.0: try using execute instead

Performs the HTTP get request and returns the response.

Arguments

This method accepts no arguments.

Notes

• The get method for this request has been moved to a get method that’s been generically implemented for all APIs and services, implemented on the google_maps::Client struct.

  Try using execute method for a somewhat similar result. The main difference is that the execute method will validate the request and build the URL string, whereas the previous get implementation (that’s been deprecated) would blindly submit the request, if any.

Trait Implementations

impl<'r> Debug for ForwardRequest<'r>

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

Formats the value using the given formatter.

impl EndPoint for ForwardRequest<'_>

Defines a Google Maps API HTTP end-point for a request.

This trait returns information needed to make connect HTTP GET requests to their API end-point. It also includes some extra information for debugging and rating-limiting.

fn service_url() -> &'static str

URL for the HTTP end-point. For example, https://maps.googleapis.com/maps/api/directions. This string will be used to build the HTTP requests.

fn title() -> &'static str

Title of the API request end-point. For example Directions API or Elevation API. This title will be output in tracing messages.

fn apis() -> &'static [Api]

Returns which APIs are being used. This is used for rate-limiting on an API-basis.

fn output_format() -> Option<&'static str>

Google Maps accepts xml and json formats. Currently, this crate only supports the json format and this function should only return json for now.

impl QueryString for ForwardRequest<'_>

fn query_string(&self) -> String

Builds the URL query string for the HTTP GET request. The query string is generated from the data found in this Request structure.

Arguments

This method accepts no arguments.

Notes

• This function does not validate the request before generating the query string. However, the superior method that generates the query URL does perform validation.

• The query string is the part of the URL after the ? question mark. For example, in the URL https://example.com/over/there?name=ferret the query string is name=ferret

• There’s no benefit to working on an owned Request struct (i.e. an owned self versus an borrowed &self). percent-encoding works on borrowed UTF-8 strings. Other types, such as enums and numeric values are converted into strings. Therefore no zero-copy operations are possible with an owned self.

impl Validatable for ForwardRequest<'_>

fn validate(&self) -> Result<(), Error>

Ensures that the request is valid.

This function checks the combination of parameters to ensure that they make sense together and that Google Maps API will accept them.

For example, Google Maps will not allow both a Positional Request and a Sampled Path Request in the same query.

This function does not check parameter values for validity - i.e. it will not ensure Polylines or Latitudes/Longitudes are valid and well-formed.

Arguments

This method accepts no arguments.

Errors

• This will fail if the request struct fails validation. For example, parameters in the request conflict with one another, or the request parameters are set in a way that’s incompatible.

  For example, Google Maps Directions API cannot calculate alternative routes if waypoints have been set. This will cause a validation failure.