🗺 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.
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: -
The full documentation is available at docs.rs
What's new?
-
0.7.3: 2020-04-25: For the Distance-Matrix API, some response fields that should have been public weren't. Fixed.
-
0.7.2: 2020-04-21: Small bug fixes. Also, some logging was causing stack overflows, so it had to be disabled.
-
0.7.1: 2020-03-10: Added in as many derivable traits as possible. Changed transit fare amount from
f64
torust_decimal::Decimal
. Clean-ups as commanded by Clippy. -
0.7.1: 2020-03-10: For Time Zone API requests from this crate has moved from expressing the time in
chrono::NaiveDateTime
tochrono::DateTime<Utc>
. See the updated time zone example. -
0.7.0: 2020-03-08: Transitioned from
f64
torust_decimal::Decimal
for latitude and longitude coordinates. This eliminates rounding errors. TheDecimal
type is also hashable. Nice.LatLng
,Waypoint
,Location
types can now be used as keys for hash maps. To define aDecimal
value in your code, currently you must add therust_decimal
dependency into yourCargo.toml
file. Use thedec!()
macro like so:dec!(12.345)
. This is the preferred way to define latitude and longitude coordinates. If you do not want to add this line to yourCargo.toml
file, you may also create aDecimal
from a&str
like so:Decimal::from_str("12.345").unwrap()
. See the new examples. Also, see the rust_decimal crate for more information. -
0.7.0: 2020-03-08: To better align this crate with Rust conventions, I've converted many
String
parameters to&str
parameters. If you're receiving new compilations errors likethe trait bound google_maps::directions::response:: driving_maneuver::DrivingManeuver: std::convert::From<std::string::String> is not satisfied
you will have to change your code to borrow the string. For example, changeTransitCurrency::try_from(currency)
toTransitCurrency::try_from(¤cy)
or toTransitCurrency::try_from(&*currency)
if its aString
type. -
0.6.0: 2020-02-29: Cleaned up the
mod
anduse
declarations. To glob import everything from google_maps into your project, you can use theuse google_maps::prelude::*
convention now. -
The full change log is available on GitHub.
Example Directions API Request
use *;
let mut google_maps_client = new;
// Example request:
let directions = google_maps_client.directions
.with_travel_mode
// Ensure this date is a weekday in the future or this query will return zero
// results.
.with_arrival_time
.execute;
// Dump entire response:
println!;
Example Distance Matrix API Request
use *;
let mut google_maps_client = new;
// Example request:
let distance_matrix = google_maps_client.distance_matrix
.execute;
// Dump entire response:
println!;
Example Elevation API Positional Request
use *;
let mut google_maps_client = new;
// Example request:
let elevation = google_maps_client.elevation
// Denver, Colorado, the "Mile High City"
.for_positional_request
.execute;
// Dump entire response:
println!;
// Parsing example:
println!;
Example Geocoding API Request
use *;
let mut google_maps_client = new;
// Example request:
let location = google_maps_client.geocoding
.with_address
.execute;
// Dump entire response:
println!;
// Parsing example:
for result in &location.unwrap.results
Example Reverse Geocoding API Request
use *;
let mut google_maps_client = new;
// Example request:
let location = google_maps_client.reverse_geocoding
.with_result_type
.execute;
// Dump entire response:
println!;
// Parsing example:
for result in &location.unwrap.results
Example Time Zone API Request
use *;
let mut google_maps_client = new;
// Example request:
let time_zone = google_maps_client.time_zone.execute.unwrap;
// Dump entire response:
println!;
// Parsing example:
println!;
println!;
Example Client Settings
The Google Maps client settings can be used to change the request rate and automatic retry parameters.
use *;
use Duration;
let mut google_maps_client = new
// For all Google Maps Platform APIs, the client will limit 2 sucessful
// requests for every 10 seconds:
.with_rate
// For unsuccessful request attempts, the client will attempt 10 retries
// before giving up:
.with_max_retries
// 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
// Returns the `ClientSettings` struct to the caller. This struct is used to
// make Google Maps Platform requests.
.finalize;
Geolocation API
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! I'm not always fast at responding but I will respond. Thanks!
To do
- Track both requests and request elements for rate limiting.
- Make a generic get() function for that can be used by all APIs.
- Considering move from
reqwest
to a lighter-weight HTTP client. - Look into making APIs optional, i.e. as features. Possible? Desirable?
- Look into integrating yaiouom.
- Convert explicit query validation to session types wherever reasonable.
- Places API. 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.
- Roads API. 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.