google_maps/geocoding/reverse/with_result_types.rs
1use crate::types::PlaceType;
2
3// -----------------------------------------------------------------------------
4
5impl crate::geocoding::ReverseRequest<'_> {
6 /// Restricts the results from the geocoder to the specified result type(s).
7 ///
8 /// # Arguments:
9 ///
10 /// * `result_type` - A single result type filter.
11 ///
12 /// # Description:
13 ///
14 /// A filter of one or more result types. If the parameter contains multiple
15 /// result types, the API returns all addresses that match any of the types.
16 /// A note about processing: The `result_type` parameter does not _restrict_
17 /// the search to the specified location type(s). Rather, the `result_type`
18 /// acts as a post-search filter: the API fetches all results for the
19 /// specified `latlng`, then discards those results that do not match the
20 /// specified result type(s). The following values are supported:
21 ///
22 /// * `PlaceType::StreetAddress` indicates a precise street address.
23 ///
24 /// * `PlaceType::Route` indicates a named route (such as "US 101").
25 ///
26 /// * `PlaceType::Intersection` indicates a major intersection, usually of
27 /// two major roads.
28 ///
29 /// * `PlaceType::Political` indicates a political entity. Usually, this
30 /// type indicates a polygon of some civil administration.
31 ///
32 /// * `PlaceType::Country` indicates the national political entity, and is
33 /// typically the highest order type returned by the Geocoder.
34 ///
35 /// * `PlaceType::AdministrativeAreaLevel1` indicates a first-order civil
36 /// entity below the country level. Within the United States, these
37 /// administrative levels are states. Not all nations exhibit these
38 /// administrative levels. In most cases,
39 /// `PlaceType::AdministrativeAreaLevel1` short names will closely match
40 /// ISO 3166-2 subdivisions and other widely circulated lists; however
41 /// this is not guaranteed as our geocoding results are based on a variety
42 /// OF signals and location data.
43 ///
44 /// * `PlaceType::AdministrativeAreaLevel2` indicates a second-order civil
45 /// entity below the country level. Within the United States, these
46 /// administrative levels are counties. Not all nations exhibit these
47 /// administrative levels.
48 ///
49 /// * `PlaceType::AdministrativeAreaLevel3` indicates a third-order civil
50 /// entity below the country level. This type indicates a minor civil
51 /// division. Not all nations exhibit these administrative levels.
52 ///
53 /// * `PlaceType::AdministrativeAreaLevel4` indicates a fourth-order civil
54 /// entity below the country level. This type indicates a minor civil
55 /// division. Not all nations exhibit these administrative levels.
56 ///
57 /// * `PlaceType::AdministrativeAreaLevel5` indicates a fifth-order civil
58 /// entity below the country level. This type indicates a minor civil
59 /// division. Not all nations exhibit these administrative levels.
60 ///
61 /// * `PlaceType::ColloquialArea` indicates a commonly-used alternative name
62 /// for the entity.
63 ///
64 /// * `PlaceType::Locality` indicates an incorporated city or town political
65 /// entity.
66 ///
67 /// * `PlaceType::Sublocality` indicates a first-order civil entity below a
68 /// locality. For some locations may receive one of the additional types:
69 /// `PlaceType::SublocalityLevel1` to `PlaceType::SublocalityLevel5`. Each
70 /// sublocality level is a civil entity. Larger numbers indicate a smaller
71 /// geographic area.
72 ///
73 /// * `PlaceType::Neighborhood` indicates a named neighborhood.
74 ///
75 /// * `PlaceType::Premise` indicates a named location, usually a building or
76 /// collection of buildings with a common name.
77 ///
78 /// * `PlaceType::Subpremise` indicates a first-order entity below a named
79 /// location, usually a singular building within a collection of buildings
80 /// with a common name.
81 ///
82 /// * `PlaceType::PostalCode` indicates a postal code as used to address
83 /// postal mail within the country.
84 ///
85 /// * `PlaceType::NaturalFeature` indicates a prominent natural feature.
86 ///
87 /// * `PlaceType::Airport` indicates an airport.
88 ///
89 /// * `PlaceType::Park` indicates a named park.
90 ///
91 /// * `PlaceType::PointOfInterest` indicates a named point of interest.
92 /// Typically, these "POI"s are prominent local entities that don't easily
93 /// fit in another category, such as "Empire State Building" or "Eiffel
94 /// Tower".
95 ///
96 /// If both `result_type` and `location_type` filters are present then the
97 /// API returns only those results that match both the `result_type` and the
98 /// `location_type values`. If none of the filter values are acceptable, the
99 /// API returns `ZERO_RESULTS`.
100 ///
101 /// # Examples:
102 ///
103 /// * A single result type filter. This example restricts results to the
104 /// neighbourhood:
105 ///
106 /// ```rust
107 /// .with_result_type(PlaceType::Neighborhood)
108 /// ```
109 ///
110 /// * Multiple component filters may be stacked together. This example
111 /// restricts results to a neighborhood and a locality:
112 ///
113 /// ```rust
114 /// .with_result_type(PlaceType::Neighborhood)
115 /// .with_result_type(PlaceType::Locality)
116 /// ```
117 #[must_use] pub fn with_result_type(
118 mut self,
119 result_type: impl Into<PlaceType>
120 ) -> Self {
121 // Add result type to ReverseRequest struct.
122 self.result_types.push(result_type.into());
123 // Return modified ReverseRequest struct to caller.
124 self
125 } // fn
126
127 /// Restricts the results from the geocoder to the specified result type(s).
128 ///
129 /// # Description
130 ///
131 /// A filter of one or more result types. If the parameter contains
132 /// multiple results types, the API returns all addresses that match any of
133 /// the types.
134 ///
135 /// If both `result_type` and `location_type` filters are present then the
136 /// API returns only those results that match both the `result_type` and the
137 /// `location_type values`. If none of the filter values are acceptable, the
138 /// API returns `ZERO_RESULTS`.
139 ///
140 /// # Example:
141 ///
142 /// * Alternatively, multiple result type filters may be passed in a single
143 /// method call by passing a slice. This example restricts results a
144 /// neighborhood and a locality:
145 ///
146 /// ```rust
147 /// .with_components(&[
148 /// PlaceType::Neighborhood,
149 /// PlaceType::Locality,
150 /// ])
151 /// ```
152 ///
153 /// # Generics
154 ///
155 /// This method uses generics to improve ergonomics. The `C` generic is
156 /// intended to represent any collection that can be iterated over, and the
157 /// `P` generic is for any type that can be converted to the `PlaceType`
158 /// type.
159 #[must_use] pub fn with_result_types<C, P>(
160 mut self,
161 result_types: C
162 ) -> Self
163 where
164 C: IntoIterator<Item = P>,
165 P: Into<PlaceType> {
166 // Add location types to ReverseRequest struct.
167 self.result_types.extend(result_types.into_iter().map(Into::into));
168 // Return modified ReverseRequest struct to caller.
169 self
170 } // fn
171} // impl