google_maps/geocoding/forward/
with_components.rs

1use crate::geocoding::Component;
2
3// -----------------------------------------------------------------------------
4
5impl crate::geocoding::ForwardRequest<'_> {
6    /// Restricts the results from the geocoder to the specified component
7    /// type(s).
8    ///
9    /// ## Arguments
10    ///
11    /// * `component` - A single component filter of `Component` type.
12    ///
13    /// ## Description
14    ///
15    /// [Component
16    /// Filtering](https://developers.google.com/maps/documentation/geocoding/intro#ComponentFiltering)
17    ///
18    /// In a Geocoding response, the Geocoding API can return address results
19    /// restricted to a specific area. You can specify the restriction using the
20    /// components filter. Filter values support the same methods of spelling
21    /// correction and partial matching as other Geocoding requests. If the
22    /// geocoder finds a partial match for a component filter, the response will
23    /// contain a `partial_match` field.
24    ///
25    /// The components that can be filtered include:
26    ///
27    /// * `Component::Route` matches the long or short name of a route.
28    ///
29    /// * `Component::Locality` matches against `locality` and `sublocality`
30    ///   types.
31    ///
32    /// * `Component::AdministrativeArea` matches all the `administrative_area`
33    ///   levels.
34    ///
35    /// Notes about component filtering:
36    ///
37    /// * If the request contains multiple component filters, the API evaluates
38    ///   them as an AND, not an OR. For example, if the request includes
39    ///   multiple countries `components=country:GB|country:AU`, the API looks
40    ///   for locations where country=GB AND country=AU, and returns
41    ///   `ZERO_RESULTS`.
42    ///
43    /// * Results are consistent with Google Maps, which occasionally yields
44    ///   unexpected `ZERO_RESULTS` responses. Using Place Autocomplete may
45    ///   provide better results in some use cases. To learn more, see [this
46    ///   FAQ](https://developers.google.com/maps/documentation/geocoding/faq#trbl_component_filtering).
47    ///
48    /// * For each address component, either specify it in the `address`
49    ///   parameter or in a `components` filter, but not both. Specifying the
50    ///   same values in both may result in `ZERO_RESULTS`.
51    ///
52    /// ## Examples:
53    ///
54    /// * A single component filter. This example restricts results to Toronto:
55    ///
56    /// ```rust
57    /// .with_component(GeocodingComponent::Locality(String::from("Toronto")))
58    /// ```
59    ///
60    /// * Multiple component filters may be stacked together. This example
61    ///   restricts results to a street in a city:
62    ///
63    /// ```rust
64    /// .with_component(GeocodingComponent::Route(String::from("Downing Street")))
65    /// .with_component(GeocodingComponent::Locality(String::from("London")))
66    /// ```
67    #[must_use] pub fn with_component(
68        mut self,
69        component: impl Into<Component>
70    ) -> Self {
71        // Add component to ForwardRequest struct.
72        self.components.push(component.into());
73        // Return modified ForwardRequest struct to caller.
74        self
75    } // fn
76
77    /// Restricts the results from the geocoder to the specified component
78    /// type(s).
79    ///
80    /// # Example:
81    ///
82    /// * Alternatively, multiple component filters may be passed in a single
83    ///   method call by passing a slice. This example restricts results to a
84    ///   street in a city:
85    ///
86    /// ```rust
87    /// .with_components(&[
88    ///     GeocodingComponent::Route(String::from("Downing Street")),
89    ///     GeocodingComponent::Locality(String::from("London")),
90    /// ])
91    /// ```
92    ///
93    /// # Generics
94    ///
95    /// This method uses generics to improve ergonomics. The `C` generic is
96    /// intended to represent any collection that can be iterated over, and the
97    /// `O` generic is for any type that can be converted to the `Component`
98    /// type.
99    #[must_use] pub fn with_components<C, O>(
100        mut self,
101        components: C
102    ) -> Self
103    where
104        C: IntoIterator<Item = O>,
105        O: Into<Component> {
106        // Add components to ForwardRequest struct.
107        self.components.extend(components.into_iter().map(Into::into));
108        // Return modified ForwardRequest struct to caller.
109        self
110    } // fn
111} // impl
google_maps/geocoding/forward/with_components.rs

google_maps/geocoding/forward/
with_components.rs
