1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
use crate::geocoding::Component;
// -----------------------------------------------------------------------------
impl crate::geocoding::ForwardRequest<'_> {
/// Restricts the results from the geocoder to the specified component
/// type(s).
///
/// ## Arguments
///
/// * `component` - A single component filter of `Component` type.
///
/// ## Description
///
/// [Component
/// Filtering](https://developers.google.com/maps/documentation/geocoding/intro#ComponentFiltering)
///
/// 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](https://developers.google.com/maps/documentation/geocoding/faq#trbl_component_filtering).
///
/// * 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:
///
/// ```rust
/// .with_component(GeocodingComponent::Locality(String::from("Toronto")))
/// ```
///
/// * Multiple component filters may be stacked together. This example
/// restricts results to a street in a city:
///
/// ```rust
/// .with_component(GeocodingComponent::Route(String::from("Downing Street")))
/// .with_component(GeocodingComponent::Locality(String::from("London")))
/// ```
#[must_use] pub fn with_component(
mut self,
component: impl Into<Component>
) -> Self {
// Add component to ForwardRequest struct.
self.components.push(component.into());
// Return modified ForwardRequest struct to caller.
self
} // fn
/// 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:
///
/// ```rust
/// .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.
#[must_use] pub fn with_components<C, O>(
mut self,
components: C
) -> Self
where
C: IntoIterator<Item = O>,
O: Into<Component> {
// Add components to ForwardRequest struct.
self.components.extend(components.into_iter().map(Into::into));
// Return modified ForwardRequest struct to caller.
self
} // fn
} // impl