[−][src]Crate google_maps

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

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 = "0.7.1". Check crates.io for the latest version number.
- Add rust_decimal = "1.3.0. Check crates.io for the latest version number.
The full documentation is available at docs.rs

What's new?

0.7.1: 2020-03-10: Added in as many derivable traits as possible. Changed transit fare amount from f64 to rust_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 to chrono::DateTime<utc>. See the updated time zone example.
0.7.0: 2020-03-08: Transitioned from f64 to rust_decimal::Decimal for latitude and longitude coordinates. This eliminates rounding errors. The Decimal type is also hashable. Nice. LatLng, Waypoint, Location types can now be used as keys for hash maps. To define a Decimal value in your code, currently you must add the rust_decimal dependency into your Cargo.toml file. Use the dec!() 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 your Cargo.toml file, you may also create a Decimal 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 like the 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, change TransitCurrency::try_from(currency) to TransitCurrency::try_from(&currency) or to TransitCurrency::try_from(&*currency) if its a String type.
0.6.0: 2020-02-29: Cleaned up the mod and use declarations. To glob import everything from google_maps into your project, you can use the use google_maps::prelude::* convention now.
The full change log is available on GitHub.

Example Directions API Request

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

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

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

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

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

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(),
    Utc::now().timestamp() + time_zone.dst_offset.unwrap() as i64 +
        time_zone.raw_offset.unwrap() as i64
);

Example Client Settings

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

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.
Look into making APIs optional, i.e. features.
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.

Modules

directions	The Directions API is a service that calculates directions between locations. You can search for directions for several modes of transportation, including transit, driving, walking, or cycling.
distance_matrix	The Distance Matrix API is a service that provides travel distance and time for a matrix of origins and destinations, based on the recommended route between start and end points.
elevation	The Elevation API provides elevation data for all locations on the surface of the earth, including depth locations on the ocean floor (which return negative values).
geocoding	The Geocoding API is a service that provides geocoding and reverse geocoding of addresses. It can be used to convert a street address to geographic coordinates (latitude & longitude), or vice versa.
prelude	Put `use google_maps::prelude::*;` in your code will to get more convenient access to everything you need. If you're not concerned with name space collisions or conflicts, you can glob import all google_maps structs and enums by using this module.
time_zone	The Time Zone API provides time offset data for locations on the surface of the earth. You request the time zone information for a specific latitude/longitude pair and date. The API returns the name of that time zone, the time offset from UTC, and the daylight savings offset.

Macros

dec

Structs

Bounds	Contains the recommended viewport for displaying the returned result, specified as two latitude & longitude values defining the southwest and northeast corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user.
ClientSettings	Use the `ClientSettings` struct's implemented methods to set your Google API key and other settings such as: rate limiting, maxium retries, & retry delay times for your requests.
DateTime	ISO 8601 combined date and time with time zone.
Decimal	`Decimal` represents a 128 bit representation of a fixed-precision decimal number. The finite set of values of type `Decimal` are of the form m / 10^e, where m is an integer such that -2⁹⁶ < m < 2⁹⁶, and e is an integer between 0 and 28 inclusive.
Duration	ISO 8601 time duration with nanosecond precision. This also allows for the negative duration; see individual methods for details.
LatLng	Latitude and longitude values must correspond to a valid location on the face of the earth. Latitudes can take any value between -90 and 90 while longitude values can take any value between -180 and 180. If you specify an invalid latitude or longitude value, your request will be rejected as a bad request.
Local	The local timescale. This is implemented via the standard `time` crate.
NaiveDate	ISO 8601 calendar date without timezone. Allows for every proleptic Gregorian date from Jan 1, 262145 BCE to Dec 31, 262143 CE. Also supports the conversion from ISO 8601 ordinal and week date.
NaiveDateTime	ISO 8601 combined date and time without timezone.
Utc	The UTC time zone. This is the most efficient time zone when you don't need the local time. It is also used as an offset (which is also a dummy type).

Enums

Api	`Api` is used to select an API to configure. For example, the Google Maps Client can be set to have different request rates for `Directions` and `Elevation` requests. This `enum` is used to select which Google Maps API you would like to configure.
Language	Specifies the language in which to return results.
PlaceType	This specifies the types or categories of a place. For example, a returned location could be a "country" (as in a nation) or it could be a "shopping mall." Also, a requested place could be a "locality" (a city) or a "street_address" This type helps define the data that is being returned or sought. See Place Types for more information.
Region	Specifies the region bias.
Tz