google_maps2 3.5.3

An unofficial Google Maps Platform client library for the Rust programming language.
Documentation 
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313

//! Directions API error types and error messages.

// -----------------------------------------------------------------------------

use crate::directions::response::status::Status;
use miette::Diagnostic;
use thiserror::Error;

// -----------------------------------------------------------------------------
//
/// Errors that may be produced by the Google Maps Directions API client.

#[derive(Debug, Diagnostic, Error)]
#[diagnostic(code(google_maps::directions::error), url(docsrs))]
pub enum Error {
    /// An arrival time may only be specified in Transit travel mode.
    ArrivalTimeIsForTransitOnly(String, String),
    /// Alternatives may not be requested when waypoints are specified.
    EitherAlternativesOrWaypoints(usize),
    /// An departure time may not be specified when an arrival time is
    /// specified.
    EitherDepartureTimeOrArrivalTime(String, String),
    /// Restrictions may not be specified when waypoints are specified.
    EitherRestrictionsOrWaypoints(usize, String),
    /// Waypoints may not be specified in Transit travel mode.
    EitherWaypointsOrTransitMode(usize),
    /// Google Maps Directions API service generated an error. See the `Status`
    /// enum for more information.
    GoogleMapsService(Status, Option<String>),
    /// The HTTP request was unsuccessful.
    HttpUnsuccessful(String),
    /// API client library attempted to parse a string that contained an invalid
    /// avoid/restrictions code. See
    /// `google_maps\src\directions\request\avoid.rs` for more information.
    InvalidAvoidCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// currency code. See
    /// `google_maps\src\directions\response\currency.rs` for more information.
    InvalidCurrencyCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// geocoder status code. See
    /// `google_maps\src\directions\response\geocoder_status.rs` for more
    /// information.
    InvalidGeocoderStatusCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// maneuver type code. See
    /// `google_maps\src\directions\response\maneuver_type.rs` for more
    /// information.
    InvalidDrivingManeuverCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// status code. See `google_maps\src\directions\response\status.rs` for
    /// more information.
    InvalidStatusCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// time zone name. See
    /// `google_maps\src\directions\response\time_zone.rs` for more information.
    InvalidTimeZoneName(String),
    /// API client library attempted to parse a string that contained an invalid
    /// traffic model code. See
    /// `google_maps\src\directions\request\traffic_model.rs` for more
    /// information.
    InvalidTrafficModelCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// transit mode code. See
    /// `google_maps\src\directions\request\transit_mode.rs` for more
    /// information.
    InvalidTransitModeCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// transit routing preference code. See
    /// `google_maps\src\directions\request\transit_route_preference.rs` for
    /// more information.
    InvalidTransitRoutePreferenceCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// travel mode code. See `google_maps\src\directions\travel_mode.rs` for
    /// more information.
    InvalidTravelModeCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// unit system code. See
    /// `google_maps\src\directions\request\unit_system.rs` for more
    /// information.
    InvalidUnitSystemCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// vehicle type code. See `google_maps\src\directions\vehicle_type.rs` for
    /// more information.
    InvalidVehicleTypeCode(String),
    /// API client library attempted to parse a string that contained an invalid
    /// departure time. See
    /// `google_maps\src\directions\request\departure_time.rs` for more
    /// information.
    InvalidDepartureTime(String),
    /// The query string must be built before the request may be sent to the
    /// Google Maps Directions API service.
    QueryNotBuilt,
    /// The request must be validated before a query string may be built.
    RequestNotValidated,
    /// The dependency library Reqwest generated an error.
    #[cfg(feature = "enable-reqwest")]
    Reqwest(crate::ReqError),
    /// The dependency library Reqwest generated an error. The error could
    /// not be passed normally so a `String` representation is passed instead.
    #[cfg(feature = "enable-reqwest")]
    ReqwestMessage(String),
    /// The dependency library Serde JSON generated an error.
    SerdeJson(serde_json::error::Error),
    /// Too many waypoints specified.
    TooManyWaypoints(usize),
    /// Transit mode may only be specified in Transit travel mode.
    TransitModeIsForTransitOnly(String, String),
    /// Transit routing preference may only be specified in Transit travel mode.
    TransitRoutePreferenceIsForTransitOnly(String, String),
} // enum

// -----------------------------------------------------------------------------

impl std::fmt::Display for Error {
    /// This trait converts the error code into a format that may be presented
    /// to the user.
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match self {
            Self::ArrivalTimeIsForTransitOnly(travel_mode, arrival_time) => write!(f,
                "Google Maps Directions API client: \
                The with_arrival_time() method may only be used when with_travel_mode() is set to `TravelMode::Transit`. \
                The travel mode is set to `{travel_mode}` and the arrival time is set to `{arrival_time}`. \
                Try again either with a travel mode of `TravelMode::Transit` or no arrival time."),
            Self::EitherAlternativesOrWaypoints(waypoint_count) => write!(f,
                "Google Maps Directions API client: \
                The with_alternatives() method cannot be set to `true` if with_waypoints() has been set. \
                {waypoint_count} waypoint(s) are set. \
                Try again either with no waypoints or no alternatives."),
            Self::EitherDepartureTimeOrArrivalTime(arrival_time, departure_time) => write!(f,
                "Google Maps Directions API client: \
                The with_departure_time() method cannot be used when with_arrival_time() has been set. \
                The arrival time is set to `{arrival_time}` and the departure time is set to `{departure_time}`. \
                Try again either with no arrival time or no departure time."),
            Self::EitherRestrictionsOrWaypoints(waypoint_count, restrictions) => write!(f,
                "Google Maps Directions API client: \
                The with_restrictions() method cannot be used when with_waypoints() has been set. \
                {waypoint_count} waypoint(s) are set and the restriction(s) are set to `{restrictions}`. \
                Try again either with no waypoints or no restrictions."),
            Self::EitherWaypointsOrTransitMode(waypoint_count) => write!(f,
                "Google Maps Directions API client: \
                The with_waypoints() method cannot be used when with_travel_mode() is set to `TravelMode::Transit`. \
                {waypoint_count} waypoint(s) are set. \
                Try again either with a different travel mode or no waypoints."),
            Self::GoogleMapsService(status, error_message) => match error_message {
                // If the Google Maps Directions API service generated an error
                // message, return that:
                Some(error_message) => write!(f, "Google Maps Directions API service: {error_message}"),
                // If the Google Maps Directions API service did not generate an
                // error message, return a generic message derived from the
                // response status:
                None => match status {
                    Status::InvalidRequest => write!(f, "Google Maps Directions API service: \
                        Invalid request. \
                        This may indicate that the query (address, components, or latlng) is missing, an invalid result type, or an invalid location type."),
                    Status::MaxRouteLengthExceeded => write!(f, "Google Maps Directions API service: \
                        Maximum route length exceeded. \
                        Try reducing the number of waypoints, turns, or instructions."),
                    Status::MaxWaypointsExceeded => write!(f, "Google Maps Directions API service: \
                        Maximum waypoints exceeded. \
                        The maximum allowed number of waypoints is 25, plus the origin and destination."),
                    Status::NotFound => write!(f, "Google Maps Directions API service: \
                        Not found. \
                        An origin, destination, or waypoint could not be geocoded."),
                    Status::Ok => write!(f, "Google Maps Directions server: \
                        Ok. \
                        The request was successful."),
                    Status::OverDailyLimit => write!(f, "Google Maps Directions API service: \
                        Over daily limit. \
                        Usage cap has been exceeded, API key is invalid, billing has not been enabled, or method of payment is no longer valid."),
                    Status::OverQueryLimit => write!(f, "Google Maps Directions API service: \
                        Over query limit. \
                        Requestor has exceeded quota."),
                    Status::RequestDenied => write!(f, "Google Maps Directions API service: \
                        Request denied. \
                        Service did not complete the request."),
                    Status::UnknownError => write!(f, "Google Maps Directions API service: \
                        Unknown error."),
                    Status::ZeroResults => write!(f, "Google Maps Directions API service: \
                        Zero results. \
                        This may occur if the geocoder was passed a non-existent address."),
                } // match
            }, // match
            Self::HttpUnsuccessful(status) => write!(f,
                "Google Maps Directions API client: \
                Could not successfully query the Google Cloud Platform service. \
                The service last responded with a `{status}` status."),
            Self::InvalidAvoidCode(avoid_code) => write!(f,
                "Google Maps Directions API client: \
                `{avoid_code}` is not a valid restrictions code. \
                Valid codes are `ferries`, `highways`, `indoor`, and `tolls`."),
             Self::InvalidCurrencyCode(currency_code) => write!(f,
                "Google Maps Directions API client: \
                `{currency_code}` is not a recognized currency code. \
                For a list of supported currencies see \
                https://en.wikipedia.org/wiki/ISO_4217"),
            Self::InvalidGeocoderStatusCode(geocoder_status_code) => write!(f,
                "Google Maps Directions API client: \
                `{geocoder_status_code}` is not a valid geocoder status code. \
                Valid codes are `OK`, and `ZERO_RESULTS`."),
            Self::InvalidDrivingManeuverCode(maneuver_type_code) => write!(f,
                "Google Maps Directions API client: \
                `{maneuver_type_code}` is not a valid maneuver type code. \
                Valid codes are `ferry`, `ferry-train`, `fork-left`, \
                `fork-right`, `keep-left`, `keep-right`, `merge`, `ramp-left`, \
                `ramp-right`, `roundabout-left`, `roundabout-right`, \
                `straight`, `turn-left`, `turn-right`, `turn-sharp-left`, \
                `turn-sharp-right`, `turn-slight-left`, `turn-slight-right`, \
                `uturn-left`, and `uturn-right`."),
            Self::InvalidStatusCode(status_code) => write!(f,
                "Google Maps Directions API client: \
                `{status_code}` is not a valid status code. \
                Valid codes are `INVALID_REQUEST`, `MAX_ROUTE_LENGTH_EXCEEDED` \
                `MAX_WAYPOINTS_EXCEEDED`, `NOT_FOUND`, `OK`, \
                `OVER_DAILY_LIMIT`, `OVER_QUERY_LIMIT`, `REQUEST_DENIED`, \
                `UNKNOWN_ERROR`, and `ZERO_RESULTS`."),
            Self::InvalidTimeZoneName(time_zone_name) => write!(f,
                "Google Maps Directions API client: \
                `{time_zone_name}` is not a recognized time zone name. \
                For a list of supported time zones see \
                https://www.iana.org/time-zones"),
            Self::InvalidTrafficModelCode(traffic_model_code) => write!(f,
                "Google Maps Directions API client: \
                `{traffic_model_code}` is not a valid traffic model code. \
                Valid codes are `best_guess`, `optimistic`, and `pessimistic`."),
            Self::InvalidTransitModeCode(transit_mode_code) => write!(f,
                "Google Maps Directions API client: \
                `{transit_mode_code}` is not a valid transit mode code. Valid codes are `bus`,
                `rail`, `subway`, `train`, and `tram`."),
            Self::InvalidTransitRoutePreferenceCode(transit_route_preference_code) =>
                write!(f, "Google Maps Directions API client: \
                `{transit_route_preference_code}` is not a valid transit route preference code. \
                Valid codes are `fewer_transfers` and `less_walking`."),
            Self::InvalidTravelModeCode(travel_mode_code) => write!(f,
                "Google Maps Directions API client: \
                `{travel_mode_code}` is not a valid travel mode code. \
                Valid codes are `bicycling`, `driving`, `transit`, and \
                `walking`."),
            Self::InvalidUnitSystemCode(unit_system_code) => write!(f,
                "Google Maps Directions API client: \
                `{unit_system_code}` is not a valid unit system code. \
                Valid codes are `imperial`, and `metric`."),
            Self::InvalidVehicleTypeCode(vehicle_type_code) => write!(f,
                "Google Maps Directions API client: \
                `{vehicle_type_code}` is not a valid vehicle type code. \
                Valid codes are `BUS`, `CABLE_CAR`, `COMMUTER_TRAIN`,  \
                `FERRY`, `FUNICULAR`, `GONDOLA_LIFT`, `HEAVY_RAIL`, \
                `HIGH_SPEED_TRAIN`, `INTERCITY_BUS`, `LONG_DISTANCE_TRAIN`, \
                `METRO_RAIL`, `MONORAIL`, `OTHER`, `RAIL`, `SHARE_TAXI`, \
                `SUBWAY`, `TRAM`, and `TROLLEYBUS`."),
            Self::InvalidDepartureTime(invalid_departure_time_string) => write!(f,
                "Google Maps Directions API client: \
                `{invalid_departure_time_string}` is not a valid departure time. \
                Valid departure times are `now`, or a UNIX timestamp."
            ),
            Self::QueryNotBuilt => write!(f,
                "Google Maps Directions API client: \
                The query string must be built before the request may be sent to the Google Cloud Maps Platform. \
                Ensure the build() method is called before run()."),
            Self::RequestNotValidated => write!(f,
                "Google Maps Directions API client: \
                The request must be validated before a query string may be built. \
                Ensure the validate() method is called before build()."),
            #[cfg(feature = "enable-reqwest")]
            Self::Reqwest(error) => write!(f, "Google Maps Directions API client in the Reqwest library: {error}"),
            #[cfg(feature = "enable-reqwest")]
            Self::ReqwestMessage(error) => write!(f, "Google Maps Geocoding API client in the Reqwest library: {error}"),
            Self::SerdeJson(error) => write!(f, "Google Maps Directions API client in the Serde JSON library: {error}"),
            Self::TooManyWaypoints(waypoint_count) => write!(f,
                "Google Maps Directions API client: \
                The maximum allowed number of waypoints is 25 plus the origin and destination. \
                {} waypoints are set. \
                Try again with {} fewer waypoint(s).",
                waypoint_count,
                waypoint_count - 25),
            Self::TransitModeIsForTransitOnly(travel_mode, transit_modes) => write!(f,
                "Google Maps Directions API client: \
                The with_transit_modes() method may only be used when with_travel_mode() is set to `TravelMode::Transit`. \
                The travel mode is set to `{travel_mode}` and the transit mode(s) are set to `{transit_modes}`. \
                Try again either with a travel mode of `TravelMode::Transit` or no transit modes."),
            Self::TransitRoutePreferenceIsForTransitOnly(travel_mode, transit_route_preference) => write!(f,
                "Google Maps Directions API client: \
                The with_transit_route_preference() method may only be used when with_travel_mode() is set to `TravelMode::Transit`. \
                The travel mode is set to `{travel_mode}` and the transit route preference is set to `{transit_route_preference}`. \
                Try again either with a travel mode of `TravelMode::Transit` or no transit route preference."),
        } // match
    } // fn
} // impl

// -----------------------------------------------------------------------------

#[cfg(feature = "enable-reqwest")]
impl From<crate::ReqError> for Error {
    /// This trait converts from an Reqwest error type (`reqwest::Error`) into a
    /// Google Maps Directions API error type
    /// (`google_maps::directions::error::Error`) by wrapping it inside. This
    /// function is required to use the `?` operator.
    fn from(error: crate::ReqError) -> Self {
        Self::Reqwest(error)
    } // fn
} // impl

// -----------------------------------------------------------------------------

impl From<serde_json::error::Error> for Error {
    /// This trait converts from an Serde JSON (`serde_json::error::Error`)
    /// error type into a Google Maps Directions API error type
    /// (`google_maps::directions::error::Error`) by wrapping it inside. This
    /// function is required to use the `?` operator.
    fn from(error: serde_json::error::Error) -> Self {
        Self::SerdeJson(error)
    } // fn
} // impl