Crate google_maps[−][src]
Expand description
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.
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 = "2.1"
. Check crates.io for the latest version number. -
Optionally, add
rust_decimal = "1"
andrust_decimal_macros = "1"
for access to the dec! macro. This macro can be used to define decimal numbers in your program. This is useful for efficiently hard-coding latitudes and longitudes in your code.
-
-
The full documentation is available at docs.rs
What’s new?
-
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 theCargo.toml
file. Now, theenable-reqwest
feature starts with no reqwest features so that Web Assembly users may rely on reqwest’s JS fetch API. Also, changedquery_string()
toquery_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. See CHANGELOG.md for example usage. -
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 thetracing
crate. -
2.0.1: 2021-07-15: Now supports a user-configured Reqwest client in the Google Maps client builder.
ClientSettings::new("YOUR_API_KEY_HERE").with_reqwest_client(your_reqwest_client).finalize();
-
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::*;
use rust_decimal_macros::dec;
let 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))?),
)
.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::*;
use rust_decimal_macros::dec;
let 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))?),
],
).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::*;
use rust_decimal_macros::dec;
let 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))?)
.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 = ClientSettings::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::*;
use rust_decimal_macros::dec;
let 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))?,
)
.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::*;
use rust_decimal_macros::dec;
let 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))?,
// 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: {}", Utc::now().to_rfc2822());
if let Some(time_zone_id) = time_zone.time_zone_id {
println!(
"Time in {}: {}",
time_zone_id.name(),
Local::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 = 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, std::time::Duration::from_secs(10))
// Returns the `ClientSettings` struct to the caller. This struct is used to
// make Google Maps Platform requests.
.finalize();
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 API Client feature flags:
- directions
- distance_matrix
- elevation
- geocoding
- time_zone
Reqwest feature flags:
- 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 = "2.1", 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 = ["directions", "distance_matrix", "elevation", "geocoding", "time_zone", "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
- 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.
Modules
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.
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.
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).
Google Maps Platform API error types and error messages.
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.
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.
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.
Structs
Contains the recommended viewport for displaying the returned result, specified as two latitude & longitude pairs 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.
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.
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.
Enums
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.
Specifies the language in which to return results.
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.
Specifies the region bias.