🗺 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.3"
. Check crates.io for the latest version number. -
Optionally, add
rust_decimal = "1"
andrust_decimal_macros = "1"
for access to thedec!
macro. This macro can be used to define decimal numbers in your program. This is useful for efficiently hard-coding latitudes and longitudes into your code for development and testing.
-
-
The full documentation is available at docs.rs
What's new?
-
Release notes are available on GitHub.
-
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 *;
let google_maps_client = new;
// Example request:
let directions = google_maps_client.directions
.with_travel_mode
.execute
.await?;
// Dump entire response:
println!;
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 *;
let google_maps_client = new;
// Example request:
let distance_matrix = google_maps_client.distance_matrix.execute.await?;
// Dump entire response:
println!;
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 *;
let google_maps_client = new;
// Example request:
let elevation = google_maps_client.elevation
// Denver, Colorado, the "Mile High City"
.for_positional_request
.execute
.await?;
// Dump entire response:
println!;
// Display all results:
if let Some = &elevation.results
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 *;
let google_maps_client = new;
// Example request:
let location = google_maps_client.geocoding
.with_address
.execute
.await?;
// Dump entire response:
println!;
// Print latitude & longitude coordinates:
for result in location.results
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 *;
let google_maps_client = new;
// Example request:
let location = google_maps_client.reverse_geocoding
.with_result_type
.execute
.await?;
// Dump entire response:
println!;
// Display all results:
for result in location.results
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 *;
let google_maps_client = new;
// Example request:
let time_zone = google_maps_client.time_zone.execute.await?;
// Dump entire response:
println!;
// Usage example:
println!;
if let Some = time_zone.time_zone_id
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 *;
let google_maps_client = new
// For all Google Maps Platform APIs, the client will limit 2 sucessful
// requests for every 10 seconds:
.with_rate
// 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:
- autocomplete
- directions
- distance_matrix
- elevation
- geocoding
- places
- roads
- time_zone
- 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.
= {
version = "3.0",
= false,
= [
"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
).
= [
# Google Maps crate features:
"directions",
"distance_matrix",
"elevation",
"geocoding",
"time_zone",
"autocomplete",
"roads",
"places",
# reqwest features:
"enable-reqwest",
"reqwest/default-tls",
"reqwest/gzip",
# rust_decimal features:
"rust_decimal/serde"
]
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.
- Convert explicit query validation to session types wherever reasonable.
- Places API. Only partly implemented. If you would like to have any missing pieces implemented, please contact me.
- Roads API. Only partly implemented. If you would like to have any missing pieces implemented, please contact me.