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.

Example Directions API Request

use google_maps::*;
let mut my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);

// Example request:

let directions = DirectionsRequest::new(
    &mut my_settings,
    // 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(45.403_509, -75.618_904).unwrap()),
)
.with_travel_mode(TravelMode::Transit)
.with_arrival_time(PrimitiveDateTime::new(
    // Ensure this date is a weekday in the future or this query will return
    // zero results.
    Date::try_from_ymd(2020, 2, 6).unwrap(),
    Time::try_from_hms(13, 00, 0).unwrap()
))
.execute().unwrap();

// Dump entire response:

println!("{:#?}", directions);

Example Distance Matrix API Request

use google_maps::*;
let mut my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);

// Example request:

let distance_matrix = DistanceMatrixRequest::new(
    &mut my_settings,
    // 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(37.387_316, -122.060_008).unwrap()),
    ],
)
.execute().unwrap();

// Dump entire response:

println!("{:#?}", distance_matrix);

Example Elevation API Positional Request

use google_maps::*;
let mut my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);

// Example request:

let elevation = ElevationRequest::new(&mut my_settings)
    // Denver, Colorado, the "Mile High City"
    .for_positional_request(LatLng::try_from(39.739_154, -104.984_703).unwrap())
    .execute().unwrap();

// Dump entire response:

println!("{:#?}", elevation);

// Parsing example:

println!("Elevation: {} meters", elevation.results.unwrap()[0].elevation);

Example Geocoding API Request

use google_maps::*;
let mut my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);

// Example request:

let location = GeocodingRequest::new(&mut my_settings)
    .with_address("10 Downing Street London")
    .execute().unwrap();

// Dump entire response:

println!("{:#?}", location);

// Parsing example:

for result in &location.results {
    println!("{}", result.geometry.location)
}

Example Reverse Geocoding API Request

use google_maps::*;
let mut my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);

// Example request:

let location = GeocodingReverseRequest::new(
    &mut my_settings,
    // 10 Downing St, Westminster, London
    LatLng::try_from(51.503_364, -0.127_625).unwrap(),
)
.with_result_type(PlaceType::StreetAddress)
.execute().unwrap();

// Dump entire response:

println!("{:#?}", location);

// Parsing example:

for result in &location.results {
    for address_component in &result.address_components {
        print!("{} ", address_component.short_name);
    }
    println!(""); // New line.
}

Example Time Zone API Request

use google_maps::*;
let mut my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);

// Example request:

let time_zone = TimeZoneRequest::new(
    &mut my_settings,
    // St. Vitus Cathedral in Prague, Czechia
    LatLng::try_from(50.090_903, 14.400_512).unwrap(),
    PrimitiveDateTime::new(
        // Tuesday February 15, 2022
        Date::try_from_ymd(2022, 2, 15).unwrap(),
        // 6:00:00 pm
        Time::try_from_hms(18, 00, 0).unwrap(),
    ),
).execute().unwrap();

// Dump entire response:

println!("{:#?}", time_zone);

// Parsing example:

use std::time::{SystemTime, UNIX_EPOCH};

let unix_timestamp =
    SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();

println!("Time at your computer: {}", unix_timestamp);

println!("Time in {}: {}",
    time_zone.time_zone_id.unwrap(),
    unix_timestamp as i64 + time_zone.dst_offset.unwrap() as i64 +
        time_zone.raw_offset.unwrap() as i64
);

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!

Change Log

0.4.6: 2020-02-19: Emergency update! Case conflict for TransitMode. Had to force to lower case in URL query string builder.
0.4.6: 2020-02-19: Connected Travis CI.
0.4.6: 2020-02-19: Added support for sub-steps in Directions API.
0.4.5: 2020-02-19: Emergency update! Custom deserializer for Durations was not included in the 0.4.4 release.
0.4.4: 2020-02-19: Interface should be stablizing.
0.4.4: Added some helper functions for destructuring responses.
0.4.4: Ensured response structures are all declared as public.
0.4.4: 2020-02-18: Aliased Distance and Duration structs to DirectionsDistance and DirectionsDuration respectively to prevent name collisions.
0.4.4: 2020-02-18: Changed DirectionsDuration.value type from u32 to time::Duration type.
0.4.4: 2020-02-18: Dropped my custom Serde deserializer in favour of the time crate's built-in Serde feature.
0.4.4: 2020-02-17: Added support for waypoint optimization.
0.4.3: 2020-02-09: Happy 15th birthday to Google Maps!
0.4.3: 2020-02-09: Ensured request rate limiting was applied to all API requests.
0.4.2: 2020-02-06: Unix timestamps received from the Google Maps Platform are now automatically deserialized into time::PrimitiveDateTime structs for convenience.
0.4.2: 2020-02-06: Removed precision limit for Google Maps Platform requests.
0.4.1: 2020-02-06: Added time zone and currency enumerations for look-up tables, conversions, and additional handling to be added in the future.
0.4.1: 2020-02-06: Fixed some errors in the examples.
0.4.1: 2020-02-05: Some internal restructuring to make the library more consistent. Improved many comments, better documentation.
0.4.0: ⚠ Breaking change: API keys are no longer passed directly to Google Maps requests. Now, a structure containing your API key, and several optional settings, is passed instead. For example:

Before:

let location = GeocodingReverseRequest::new(
    YOUR_GOOGLE_API_KEY_HERE,
    // 10 Downing St, Westminster, London
    LatLng { lat: 51.5033635, lng: -0.1276248 }
)

After. Note to Rust newbies: you may need to change the ? to an .unwrap() if you're running these examples in your main() function.

let my_settings = ClientSettings::new(YOUR_GOOGLE_API_KEY_HERE);
let location = GeocodingReverseRequest::new(
    &mut my_settings,
    // 10 Downing St, Westminster, London
    LatLng(LatLng::try_from(51.5033635, -0.1276248)?),
)

0.4.0: ⚠ Breaking change: All response structures, such as DirectionsResponse, have been altered.
0.4.0: ⚠ Breaking change: All LatLng enum variants have had the { lat, lng } fields removed in favour of LatLng structs. Use LatLng::try_from(lat, lng) to define latitude/longitude pairs. See the updated examples.
0.4.0: ⚠ Breaking change: The Elevation API methods positional_request() & sampled_path_request() have been renamed to for_positional_request() & for_sampled_path_request() respectively. See the updated examples.
0.4.0: ⚠ Breaking change: All f32 fields have been increased to f64 fields.
0.4.0: Implemented automatic retry with exponential backoff. This client library will now attempt to query the Google Cloud Platform several times before giving up and returning an error. Temporary network hiccups will no longer cause your program to fail.
0.4.0: Implemented request rate limiting. Each API can have different request rate limits.
0.4.0: Now implements the log crate with some logging messages for debugging.

To do

Track both requests and request elements for rate limiting.
Make a generic get() function for that can be used by all APIs.
Look into making APIs optional, i.e. features. Possible? Desirable?
Look into the prelude::* convention.
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.

google_maps 0.4.6