🗺 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, Time Zone API, parts of the Places API, and parts of the Roads API.

Welcome

This crate is expected to work well and have the more important Google Maps features implemented. It should work well because serde and, by default, reqwest do most of the heavy lifting!

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 = "3.1". Check crates.io for the latest version number.

• The full documentation is available at docs.rs

What's new?

• 3.1.0: 2022-11-27: ⚠ Breaking change: Geometry.location_type is now an Option.

• 3.1.0: 2022-11-27: Add basic support for Google Maps Places Text Search and Places Details.

• 3.0.1: 2022-10-01: Added UNKNOWN_ERROR variant to Directions API's geocoder status.

• 3.0.0: 2022-09-03: ⚠ Breaking change: LatLng::try_from had to be renamed to LatLng::try_from_dec to fix name collision with the TryFrom trait. Added try_from_f32 and try_from_f64 methods for the LatLng type.

• 3.0.0: 2022-09-04: Initial support for Google Maps Roads API: the Snap To Roads and the Nearest Roads services have been implemented. Unsure about supporting Speed Limits since, according to the documentation, it requires a special Google Maps plan.

• 3.0.0: 2022-09-03: Optional basic support for the geo crate and GeoRust ecosystem. This support may be enabled using the geo feature flag. When the geo feature is enabled, some types may loose support for serde serialization & deserialization. If I've missed something you want or if you think of a better way of doing this, feel free to reach out. See CHANGELOG.md for more information on this update.

• 3.0.0: 2022-09-04: ClientSettings renamed to GoogleMapsClient.

• 3.0.0: 2022-08-27: Adjusted tracing log levels.

• 2.1.7: 2022-08-27: String to enum table look-ups are now powered by the phf (perfect hash functions) crate. Added manual implementations of serde deserializers for Google Maps client types, which take advantage of the new phf tables.

• 2.1.7: 2022-08-27: Google Maps client types now implement FromStr which gives access to parse. For example: let the_golden_boy: LatLng = "49.8845224,-97.1469436".parse()?;

• 2.1.7: 2022-08-22: Added debug logging message to show Google Maps client's request activity.

• 2.1.6: 2022-08-19: Support for geocoding from Google Maps Place IDs. Thank you E-gy!

• 2.1.6: 2022-04-10: country was moved up the hierarchy because it's now being shared amongst several APIs. Made google_maps::country module public.

• 2.1.5: 2022-03-23: Partial support for the Google Maps Places API. Implemented the Place Autocomplete and Query Autocomplete services.

• 2.1.3: 2021-07-22: Web Assembly (WASM) support: if Google Maps API Client's default-features are set to false, all desired reqwest features (brotli, rustls, etc.) must be manually added to the Cargo.toml file. Now, the enable-reqwest feature starts with no reqwest features so that Web Assembly users may rely on reqwest's JS fetch API. Also, changed query_string() to query_url(). See CHANGELOG.md for example usage.

• 2.1.2: 2021-07-18: Made more dependencies optional. This adds the ability to slim down this client when needed. Also, spruced up the query_string() methods.

• 2.1.1: 2021-07-18: House-keeping. Fixed issue with Google Maps API features. Added support for using your own HTTP client.

• 2.1.0: 2021-07-17: Transitioned from an in-house retry/backoff implementation to the backoff crate. Google Maps APIs are now optional through the use of feature flags. Improved examples.

• 2.0.2: 2021-07-16: Added support for using rustls-tls in reqwest dependency - thanks seanpianka! Transitioned from log crate to the tracing crate.

• 2.0.1: 2021-07-15: Now supports a user-configured Reqwest client in the Google Maps client builder. GoogleMapsClient::new("YOUR_API_KEY_HERE").with_reqwest_client(your_reqwest_client).build();

• 2.0.0: 2021-07-13: The Rust Google Maps client is now async thanks to seanpianka!

• The full change log is available on GitHub.

Example Directions API Request

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.

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::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_f64(45.403_509, -75.618_904)?),
)
.with_travel_mode(TravelMode::Driving)
.execute()
.await?;

// Dump entire response:

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

Example Distance Matrix API Request

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.

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::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(dec!(37.387_316), dec!(-122.060_008))?),
    ],
).execute().await?;

// Dump entire response:

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

Example Elevation API Positional Request

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).

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::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(dec!(39.739_154), dec!(-104.984_703))?)
    .execute()
    .await?;

// Dump entire response:

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

// Display all results:

if let Some(results) = &elevation.results {
    for result in results {
        println!("Elevation: {} meters", result.elevation)
    }
}

Example Geocoding API Request

The Geocoding API is a service that provides geocoding and reverse geocoding of addresses. Geocoding is the process of converting addresses (like a street address) into geographic coordinates (like latitude and longitude), which you can use to place markers on a map, or position the map.

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::new("YOUR_GOOGLE_API_KEY_HERE");

// Example request:

let location = google_maps_client.geocoding()
    .with_address("10 Downing Street London")
    .execute()
    .await?;

// Dump entire response:

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

// Print latitude & longitude coordinates:

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

Example Reverse Geocoding API Request

The Geocoding API is a service that provides geocoding and reverse geocoding of addresses. Reverse geocoding is the process of converting geographic coordinates into a human-readable address.

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::new("YOUR_GOOGLE_API_KEY_HERE");

// Example request:

let location = google_maps_client.reverse_geocoding(
    // 10 Downing St, Westminster, London
    LatLng::try_from_dec(dec!(51.503_364), dec!(-0.127_625))?,
)
.with_result_type(PlaceType::StreetAddress)
.execute()
.await?;

// Dump entire response:

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

// Display all results:

for result in location.results {
    println!(
        "{}",
        result.address_components.iter()
            .map(|address_component| address_component.short_name.to_string())
            .collect::<Vec<String>>()
            .join(", ")
    );
}

Example Time Zone API Request

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.

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::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(dec!(50.090_903), dec!(14.400_512))?,
     // The time right now in UTC (Coordinated Universal Time)
     Utc::now()
).execute().await?;

// Dump entire response:

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

// Usage example:

println!("Time at your computer: {}", Local::now().to_rfc2822());

if let Some(time_zone_id) = time_zone.time_zone_id {
    println!(
    	"Time in {}: {}",
        time_zone_id.name(),
        Utc::now().with_timezone(&time_zone_id).to_rfc2822()
    );
}

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.

Example Client Settings

The Google Maps client settings can be used to change the request rate and automatic retry parameters.

use google_maps::prelude::*;

let google_maps_client = GoogleMapsClient::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, std::time::Duration::from_secs(10))
    // Returns the `GoogleMapsClient` struct to the caller. This struct is used
    // to make Google Maps Platform requests.
    .build();

Feature Flags

It is possible to change the Reqwest features that are in turn used by the Google Maps API client through feature flags. It is also possible to only include desired Google Maps APIs by using Cargo.toml feature flags.

Google Maps Client feature flags:

• directions
• distance_matrix
• elevation
• geocoding
• time_zone
• autocomplete
• roads
• enable-reqwest (uses reqwest for querying Google Maps API).
• geo (support for geo crate types)

Note: The Places autocomplete APIs have been put in the autocomplete feature flag. The rest of the Places APIs will be put under the places feature flag.

Reqwest feature flags (for use with enable-reqwest only):

• native-tls
• rustls
• gzip
• brotli

Feature flag usage example: This example will only include the Google Maps Directions API. Reqwest will secure the connection using the Rustls library, and has brotli compression enabled.

google_maps = {
	version = "3.0",
	default-features = false,
	features = [
		"directions",
		"enable-reqwest",
		"rustls",
		"brotli"
	]
}

Default feature flag configuration: By default, the Google Maps client includes all implemented Google Maps APIs. Reqwest will secure the connection using the system-native TLS (native-tls), and has gzip compression enabled (gzip).

default = [
	# Google Maps crate features:
	"directions",
	"distance_matrix",
	"elevation",
	"geocoding",
	"time_zone",
	"autocomplete",
	"roads",

	# reqwest features:
	"enable-reqwest",
	"reqwest/default-tls",
	"reqwest/gzip",
]

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

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. Convert explicit query validation to session types wherever reasonable.
4. Places API. Only partly implemented. If you would like to have any missing pieces implemented, please contact me.
5. Roads API. Only partly implemented. If you would like to have any missing pieces implemented, please contact me.