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
//! # google_maps
//!
//! 🗺 An unofficial Google Maps Platform client library for the Rust
//! programming language. This client currently implements the Directions API,
//! Distance Matrix API, Elevation API, Geocoding API, and Time Zone API.
//!
//! ![alt text](https://camo.githubusercontent.com/5b3f625c9385e359f735cac1f23b5cd35332cd0a/68747470733a2f2f7777772e61726b697465712e63612f6372617465732f676f6f676c655f6d6170732f62616e6e65722e6a7067 "Unofficial Google Maps Platform Client for Rust")
//!
//! # Welcome
//!
//! This crate is expected to work well and have the more important Google Maps
//! features implemented. It should work well because Reqwest and Serde do most
//! of the heavy lifting! While it's an early release, this crate should work
//! fine as is for most people.
//!
//! I created this client library because I needed several Google Maps Platform
//! features for a project that I'm working on. So, I've decided to spin my
//! library off into a public crate. This is a very small token of gratitude and
//! an attempt to give back to the Rust community. I hope it saves someone out
//! there some work.
//!
//! # Before You Begin
//!
//! * In your project's `Cargo.toml` file, under the `[dependencies]` section:
//!
//!     * Add `google_maps = "1.0.2"`. Check
//!         [crates.io](https://crates.io/crates/google_maps) for the latest
//!         version number.
//!
//!     * Add `rust_decimal = "1.6.0`. Check
//!         [crates.io](https://crates.io/crates/rust_decimal) for the
//!         latest version number.
//!
//! * The full documentation is available at
//! [docs.rs](https://docs.rs/google_maps/)
//!
//! # What's new?
//!
//! * 1.0.2: 2020-08-07: Corrected error where string formatted for display were
//! being sent to the Google Maps Platform API. Thanks
//! [victorct-pronto](https://github.com/victorct-pronto)!
//!
//! * 1.0.1: 2020-05-25: Ensuring all public structures use Serde's serialize
//! and deserialize traits. Thanks [qrayven](https://github.com/qrayven)!
//!
//! * 1.0.0: 2020-05-16: Inteface stable.
//!
//! * The full [change
//! log](https://github.com/leontoeides/google_maps/blob/master/CHANGELOG.md) is
//! available on GitHub.
//!
//! ## Example Directions API Request
//!
//! ```rust
//! use google_maps::prelude::*;
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
//!
//! // Example request:
//!
//! let directions = google_maps_client.directions(
//!     // Origin: Canadian Museum of Nature
//!     Location::Address(String::from("240 McLeod St, Ottawa, ON K2P 2R1")),
//!     // Destination: Canada Science and Technology Museum
//!     Location::LatLng(LatLng::try_from(dec!(45.403_509), dec!(-75.618_904)).unwrap()),
//! )
//! .with_travel_mode(TravelMode::Transit)
//! // Ensure this date is a weekday in the future or this query will return zero
//! // results.
//! .with_arrival_time(NaiveDate::from_ymd(2020, 3, 2).and_hms(13, 00, 0))
//! .execute();
//!
//! // Dump entire response:
//!
//! println!("{:#?}", directions);
//! ```
//!
//! ## Example Distance Matrix API Request
//!
//! ```rust
//! use google_maps::prelude::*;
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
//!
//! // Example request:
//!
//! let distance_matrix = google_maps_client.distance_matrix(
//!     // Origins
//!     vec![
//!         // Microsoft
//!         Waypoint::Address(String::from("One Microsoft Way, Redmond, WA 98052, United States")),
//!         // Cloudflare
//!         Waypoint::Address(String::from("101 Townsend St, San Francisco, CA 94107, United States")),
//!     ],
//!     // Destinations
//!     vec![
//!         // Google
//!         Waypoint::PlaceId(String::from("ChIJj61dQgK6j4AR4GeTYWZsKWw")),
//!         // Mozilla
//!         Waypoint::LatLng(LatLng::try_from(dec!(37.387_316), dec!(-122.060_008)).unwrap()),
//!     ],
//! )
//! .execute();
//!
//! // Dump entire response:
//!
//! println!("{:#?}", distance_matrix);
//! ```
//!
//! ## Example Elevation API Positional Request
//!
//! ```rust
//! use google_maps::prelude::*;
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
//!
//! // Example request:
//!
//! let elevation = google_maps_client.elevation()
//!     // Denver, Colorado, the "Mile High City"
//!     .for_positional_request(LatLng::try_from(dec!(39.739_154), dec!(-104.984_703)).unwrap())
//!     .execute();
//!
//! // Dump entire response:
//!
//! println!("{:#?}", elevation);
//!
//! // Parsing example:
//!
//! println!("Elevation: {} meters", elevation.unwrap().results.unwrap()[0].elevation);
//! ```
//!
//! ## Example Geocoding API Request
//!
//! ```rust
//! use google_maps::prelude::*;
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
//!
//! // Example request:
//!
//! let location = google_maps_client.geocoding()
//!     .with_address("10 Downing Street London")
//!     .execute();
//!
//! // Dump entire response:
//!
//! println!("{:#?}", location);
//!
//! // Parsing example:
//!
//! for result in &location.unwrap().results {
//!     println!("{}", result.geometry.location)
//! }
//! ```
//!
//! ## Example Reverse Geocoding API Request
//!
//! ```rust
//! use google_maps::prelude::*;
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
//!
//! // Example request:
//!
//! let location = google_maps_client.reverse_geocoding(
//!     // 10 Downing St, Westminster, London
//!     LatLng::try_from(dec!(51.503_364), dec!(-0.127_625)).unwrap(),
//! )
//! .with_result_type(PlaceType::StreetAddress)
//! .execute();
//!
//! // Dump entire response:
//!
//! println!("{:#?}", location);
//!
//! // Parsing example:
//!
//! for result in &location.unwrap().results {
//!     for address_component in &result.address_components {
//!         print!("{} ", address_component.short_name);
//!     }
//!     println!(""); // New line.
//! }
//! ```
//!
//! ## Example Time Zone API Request
//!
//! ```rust
//! use google_maps::prelude::*;
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
//!
//! // Example request:
//!
//! let time_zone = google_maps_client.time_zone(
//!      // St. Vitus Cathedral in Prague, Czechia
//!      LatLng::try_from(dec!(50.090_903), dec!(14.400_512)).unwrap(),
//!      // The time right now in UTC (Coordinated Universal Time)
//!      Utc::now()
//! ).execute().unwrap();
//!
//! // Dump entire response:
//!
//! println!("{:#?}", time_zone);
//!
//! // Parsing example:
//!
//! println!("Time at your computer: {}", Local::now().timestamp());
//!
//! println!("Time in {}: {}",
//!     time_zone.time_zone_id.unwrap().name(),
//!     Utc::now().timestamp() + time_zone.dst_offset.unwrap() as i64 +
//!         time_zone.raw_offset.unwrap() as i64
//! );
//! ```
//!
//! ## Example Client Settings
//!
//! ```rust
//! use google_maps::prelude::*;
//! use std::time::Duration;
//!
//! let mut google_maps_client = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE)
//!     // For all Google Maps Platform APIs, the client will limit 2 sucessful
//!     // requests for every 10 seconds:
//!     .with_rate(Api::All, 2, Duration::from_secs(10))
//!     // For unsuccessful request attempts, the client will attempt 10 retries
//!     // before giving up:
//!     .with_max_retries(10)
//!     // For unsuccessful requests, the delay between retries is increased
//!     // after each attempt. This parameter ensures that the client will not
//!     // delay for more than 32 seconds between retries:
//!     .with_max_delay(Duration::from_secs(32))
//!     // Returns the `ClientSettings` struct to the caller. This struct is
//!     // used to make Google Maps Platform requests.
//!     .finalize();
//! ```
//!
//! ## [Geolocation API](https://developers.google.com/maps/documentation/geolocation/intro)
//!
//! Google's Geolocation API seems to be offline. While the online documentation
//! is still available and the API appears configurable through the Google Cloud
//! Platform console, the Geolocation API responds Status code `404 Not Found`
//! with an empty body to all requests. This API cannot be implemented until the
//! server responds as expected.
//!
//! # Feedback
//!
//! I would like for you to be successful with your project! If this crate is
//! not working for you, doesn't work how you think it should, or if you have
//! requests, or suggestions - please [report them to
//! me](https://github.com/leontoeides/google_maps/issues)! I'm not always fast
//! at responding but I will respond. Thanks!
//!
//! # To do:
//!
//! 1. Track both _requests_ and request _elements_ for rate limiting.
//! 2. Make a generic get() function for that can be used by all APIs.
//! 3. Look into making APIs optional, i.e. features.
//! 4. Look into the Prelude::* convention.
//! 5. Look into integrating [yaiouom](https://crates.io/crates/yaiouom).
//! 6. Convert explicit query validation to session types wherever reasonable.
//! 7. [Places API](https://developers.google.com/places/web-service/intro).
//! There are no immediate plans for supporting this API. It's quite big and I
//! have no current need for it. If you would like to have to implemented,
//! please contact me.
//! 8. [Roads API](https://developers.google.com/maps/documentation/roads/intro).
//! There are no immediate plans for supporting this API. It's quite big and I
//! have no current need for it. If you would like to have to implemented,
//! please contact me.

#![doc(html_favicon_url = "https://www.arkiteq.ca/crates/google_maps/icon.png")]
#![doc(html_logo_url = "https://www.arkiteq.ca/crates/google_maps/logo.png")]

mod bounds;
mod client_settings;
mod error;
mod language;
mod latlng;
mod place_type;
mod region;
mod request_rate;
mod serde;
pub mod directions;
pub mod distance_matrix;
pub mod elevation;
pub mod geocoding;
pub mod prelude;
pub mod time_zone;

pub use chrono::{DateTime, Duration, Local, NaiveDate, NaiveDateTime, Utc};
pub use chrono_tz::Tz;
pub use rust_decimal::Decimal;
pub use rust_decimal_macros::dec;

pub use crate::{
    bounds::Bounds, client_settings::ClientSettings, language::Language,
    latlng::LatLng, place_type::PlaceType, region::Region,
    request_rate::api::Api,
}; // use crate