google_maps/

lib.rs

//! # `google_maps`
//! ![Crates.io Version](https://img.shields.io/crates/v/google_maps)
//! ![Crates.io MSRV](https://img.shields.io/crates/msrv/google_maps)
//! ![Crates.io License](https://img.shields.io/crates/l/google_maps)
//! ![Crates.io Total Downloads](https://img.shields.io/crates/d/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, Time Zone API, and parts of the Places and
//! Roads API.
//!
//! <img src="https://www.arkiteq.io/crates/google_maps/banner.jpg" alt="Unofficial Google Maps Platform Client for Rust" width="400"/>
//!
//! # Installation
//!
//! Configure the dependencies:
//!
//! ```toml
//! [dependencies]
//! google_maps = "3.9"
//! ```
//!
//! Optionally, add `rust_decimal = "1"` and `rust_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 hard-coding latitudes and longitudes into your code for
//! testing.
//!
//! ## Feature Flags
//!
//! The desired Google Maps APIs can be enabled individually via feature flags.
//!
//! Additionally, usage of rustls for Reqwest is supported.
//!
//! ### Google Maps Client Feature Flags:
//!
//! * `address_validation` ‧ includes Google Maps Address Validation API
//! * `directions` ‧ includes Google Maps Directions API
//! * `distance_matrix` ‧ includes Google Maps Distance Matrix API
//! * `elevation` ‧ includes Google Maps Elevation API
//! * `geocoding` ‧ includes Google Maps Geocoding API
//! * `roads` ‧ includes Google Maps Roads API
//! * `time_zone` ‧ includes Google Maps Time Zone API
//! * `reqwest` ‧ uses [reqwest](https://crates.io/crates/reqwest) for
//!   querying the Google Maps API
//! * `reqwest-middleware` ‧ uses [reqwest-middleware](https://crates.io/crates/reqwest-middleware)
//!   for querying the Google Maps API
//! * `geo` ‧ support for the rust [geo](https://crates.io/crates/geo) ecosystem
//! * `polyline` ‧ allows easy type conversions from a `Route` or `Step` to a geo
//!   [LineString](https://docs.rs/geo-types/0.7.13/geo_types/geometry/struct.LineString.html)
//!
//! #### Google Maps Places API (New) Features
//!
//! * `places-new` ‧ includes all Google Maps Places API (New) services
//! * `places-new-autocomplete` ‧ Autocomplete service only
//! * `places-new-nearby-search` ‧ Nearby Search service only
//! * `places-new-place-details` ‧ Place Details service only
//! * `places-new-place-photos` ‧ Place Photos service only
//! * `places-new-text-search` ‧ Text Search service only
//!
//! #### Google Maps Places API (Legacy) Features
//!
//! * `autocomplete` ‧ includes Google Maps Places API (Legacy) Autocomplete service
//! * `places` ‧ includes Google Maps Places API (Legacy)
//!
//! Note: the `autocomplete` feature covers the Places API autocomplete-related services:
//! [Place Autocomplete requests](https://docs.rs/google_maps/latest/google_maps/prelude/struct.ClientSettings.html#method.place_autocomplete)
//! and [Query Autocomplete requests](https://docs.rs/google_maps/latest/google_maps/prelude/struct.ClientSettings.html#method.query_autocomplete).
//! All other Places API services are covered by the `places` feature.
//!
//! ### Default Feature Flags
//!
//! 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`).
//!
//! ```toml
//! default = [
//!     # google_maps default features:
//!     "address_validation",
//!     "directions",
//!     "distance_matrix",
//!     "elevation",
//!     "geocoding",
//!     "time_zone",
//!     "roads",
//!     "places-new",
//!
//!     # reqwest default features:
//!     "reqwest",
//!     "reqwest-default-tls",
//!     "reqwest-http2",
//!     "reqwest-brotli",
//!
//!     # rust_decimal default features:
//!     "decimal-serde",
//! ]
//! ```
//!
//! #### 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.
//!
//! ```toml
//! google_maps = {
//!     version = "3.9",
//!     default-features = false,
//!     features = [
//!         "directions",
//!         "reqwest",
//!         "reqwest-rustls-tls",
//!         "reqwest-brotli"
//!     ]
//! }
//! ```
//!
//! # Release Notes
//!
//! The [full changelog is available
//! here](https://github.com/leontoeides/google_maps/blob/master/CHANGELOG.md).
//!
//! Releases [are available on
//! GitHub](https://github.com/leontoeides/google_maps/releases).
//!
//! # Examples
//!
//! ## Autocomplete
//!
//! Autocomplete (New) is a web service that returns place predictions and query predictions in
//! response to an HTTP request. In the request, specify a text search string and geographic bounds
//! that controls the search area.
//!
//! Autocomplete (New) can match on full words and substrings of the input, resolving place names,
//! addresses, and plus codes. Applications can therefore send queries as the user types, to provide
//! on-the-fly place and query predictions.
//!
//! ```rust
//! let google_maps_client = google_maps::Client::try_new("YOUR_API_KEY_HERE")?;
//!
//! let response = google_maps_client
//!     .autocomplete("pizza")
//!     .included_primary_types(vec![google_maps::places_new::PlaceType::Restaurant])
//!     .execute()
//!     .await?;
//!
//! for suggestion in &response {
//!     println!("{}", suggestion.text());
//! }
//!
//! // User adds "sicilian" to pizza search:
//! let response = google_maps_client
//!     .next_autocomplete("pizza sicilian", response)
//!     .await?;
//!
//! for suggestion in response {
//!     println!("{}", suggestion.to_html("mark"));
//! }
//! ```
//!
//! ## Text Search
//!
//! Text Search (New) returns information about a set of places based on a string (for example,
//! "pizza in New York" or "shoe stores near Ottawa" or "123 Main Street").
//!
//! ```rust
//! let google_maps_client = google_maps::Client::try_new("YOUR_API_KEY_HERE")?;
//!
//! let response = google_maps_client
//!     .text_search("Gas in Edmonton, Alberta")
//!     .field_mask(google_maps::places_new::FieldMask::All)
//!     .execute()
//!     .await?;
//!
//! for place in response {
//!     println!("{place:#?}");
//! }
//! ```
//!
//! ## Nearby Search
//!
//! A Nearby Search (New) request takes one or more place types, and returns a list of matching
//! places within the specified area.
//!
//! ```rust
//! let google_maps_client = google_maps::Client::try_new("YOUR_API_KEY_HERE")?;
//!
//! // Restaurants within a 5,000 m radius of the Bowker Building in Edmonton
//! let response = google_maps_client
//!     .nearby_search((53.53666, -113.50795, 5_000.0))?
//!     .field_mask(google_maps::places_new::FieldMask::All)
//!     .included_primary_types(vec![google_maps::places_new::PlaceType::Restaurant])
//!     .execute()
//!     .await?;
//!
//! for place in response {
//!     println!("{place:#?}");
//! }
//! ```
//!
//! ## Place Details
//!
//! Once you have a place ID, you can request more details about a particular establishment or point
//! of interest by initiating a Place Details (New) request.
//!
//! A Place Details (New) request returns more comprehensive information about the indicated place
//! such as its complete address, phone number, user rating and reviews.
//!
//! There are many ways to obtain a place ID. You can use:
//! * Text Search (New) or Nearby Search (New)
//! * Geocoding API
//! * Routes API
//! * Address Validation API
//! * Autocomplete (New)
//!
//! You can also experiment using the [Place ID
//! Finder](https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder)
//!
//! ```rust
//! let google_maps_client = google_maps::Client::try_new("YOUR_API_KEY_HERE")?;
//!
//! let place = google_maps_client
//!     .place_details("ChIJyZXV1jsioFMRC8PGIBAJbKA")?
//!     .field_mask(google_maps::places_new::FieldMask::All)
//!     .execute()
//!     .await?;
//!
//! println!("{place:#?}");
//! ```
//!
//! ## Place Photos
//!
//! The Place Photos (New) service is a read-only API that lets you add high quality photographic
//! content to your application. Place Photos (New) gives you access to the millions of photos
//! stored in the Places database.
//!
//! When you get place information using a Place Details (New), Nearby Search (New), or Text Search
//! (New) request, you can also request photo resources for relevant photographic content. Using
//! Place Photos (New), you can then access the referenced photos and resize the image to the
//! optimal size for your application.
//!
//!
//! ```rust
//! for place in response.into_iter().take(3) {
//!     // Download and display photo as ASCII art. `places-new-ascii-art` feature must be enabled
//!     if let Ok(photo) = google_maps_client
//!         .place_photos_image(&place)?
//!         .max_width_px(1_024)
//!         .execute()
//!         .await
//!     {
//!         println!("{}", photo.display_ansi(
//!             std::num::NonZero::new(180).unwrap() // 180 columns wide
//!         )?);
//!     }
//! }
//! ```
//!
//! ## Address Validation
//!
//! The Address Validation API validates an address and its components,
//! standardizes the address for mailing, and determines the best known geocode
//! for it.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = google_maps::Client::try_new("YOUR_API_KEY_HERE")?;
//!
//! let postal_address = PostalAddress::builder()
//!     .region_code(&Country::UnitedStates)
//!     .address_lines(vec![
//!         "1600 Amphitheatre Pkwy",
//!         "Mountain View, CA, 94043"
//!     ])
//!     .build();
//!
//! let address_validation_response = google_maps_client
//!     .validate_address()
//!     .address(postal_address)
//!     .build()
//!     .execute()
//!     .await?;
//!
//! // Dump entire response:
//! println!("{address_validation_response:#?}");
//!
//! // Optional feedback step. Let Google know which address was used for the
//! // your query:
//!
//! google_maps_client
//!     .provide_validation_feedback()
//!     .conclusion(ValidationConclusion::Unused)
//!     .response_id(address_validation_response.response_id())
//!     .build()
//!     .execute()
//!     .await?;
//! ```
//!
//! ## Directions API
//!
//! 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.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_new("YOUR_GOOGLE_API_KEY_HERE");
//!
//! // Example request:
//!
//! let directions = google_maps_client.directions(
//!     // Origin: Canadian Museum of Nature
//!     Location::from_address("240 McLeod St, Ottawa, ON K2P 2R1"),
//!     // Destination: Canada Science and Technology Museum
//!     Location::try_from_f32(45.403_509, -75.618_904)?,
//! )
//! .with_travel_mode(TravelMode::Driving)
//! .execute()
//! .await?;
//!
//! // Dump entire response:
//!
//! println!("{:#?}", directions);
//! ```
//!
//! ## Distance Matrix API
//!
//! 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.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_new("YOUR_GOOGLE_API_KEY_HERE");
//!
//! // Example request:
//!
//! let distance_matrix = google_maps_client.distance_matrix(
//!     // Origins
//!     vec![
//!         // Microsoft
//!         Waypoint::from_address("One Microsoft Way, Redmond, WA 98052, United States"),
//!         // Cloudflare
//!         Waypoint::from_address("101 Townsend St, San Francisco, CA 94107, United States"),
//!     ],
//!     // Destinations
//!     vec![
//!         // Google
//!         Waypoint::from_place_id("ChIJj61dQgK6j4AR4GeTYWZsKWw"),
//!         // Mozilla
//!         Waypoint::try_from_f32(37.387_316, -122.060_008)?,
//!     ],
//! ).execute().await?;
//!
//! // Dump entire response:
//!
//! println!("{:#?}", distance_matrix);
//! ```
//!
//! ## Elevation API (Positional)
//!
//! 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).
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_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)
//!     }
//! }
//! ```
//!
//! ## Geocoding API
//!
//! 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.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_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)
//! }
//! ```
//!
//! ## Reverse Geocoding API
//!
//! 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.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_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(", ")
//!     );
//! }
//! ```
//!
//! ## Time Zone API
//!
//! 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.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_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()
//!     );
//! }
//! ```
//!
//! ### Controlling Request Settings
//!
//! The Google Maps client settings can be used to change the request rate and
//! automatic retry parameters.
//!
//! ```rust
//! use google_maps::prelude::*;
//!
//! let google_maps_client = Client::try_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 `Client` struct to the caller. This struct is used
//!     // to make Google Maps Platform requests.
//!     .build();
//! ```
//!
//! # 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](https://github.com/leontoeides/google_maps/issues)! I'm not always fast
//! at responding but I will respond. Thanks!
//!
//! # Roadmap
//!
//! - [ ] Track both _requests_ and request _elements_ for rate limiting.
//! - [ ] Convert explicit query validation to session types wherever
//!   reasonable.
//! - [ ] [Places API](https://developers.google.com/places/web-service/intro).
//!   Only partly implemented. If you would like to have any missing pieces
//!   implemented, please contact me.
//! - [ ] [Roads API](https://developers.google.com/maps/documentation/roads/intro).
//!   Only partly implemented. If you would like to have any missing pieces
//!   implemented, please contact me.
//!
//! # Author's Note
//!
//! This crate is expected to work well and have the more important Google Maps
//! features implemented. It should work well because
//! [serde](https://crates.io/crates/serde), [serde-json](https://crates.io/crates/serde-json)
//! and, by default, [reqwest](https://crates.io/crates/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.

#![forbid(unsafe_code)]
#![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)]
#![allow(
    clippy::cast_precision_loss,
    clippy::missing_errors_doc,
    clippy::module_name_repetitions,
    clippy::multiple_crate_versions,
    clippy::negative_feature_names, // suppress clippy warning re: `serde_json` crate
    clippy::too_long_first_doc_paragraph, // bah!
    clippy::too_many_lines
)]
#![doc(html_favicon_url = "https://www.arkiteq.io/crates/google_maps/icon.png")]
#![doc(html_logo_url = "https://www.arkiteq.io/crates/google_maps/logo.png")]

// Common / global modules:

mod client;
mod serde;

pub mod error;
pub mod prelude;
pub mod types;

pub mod traits;

// Optional Google Maps API modules. Their inclusion can be changed with
// feature flags:

#[cfg(any(feature = "directions", feature = "distance_matrix"))]
pub mod directions;

#[cfg(feature = "distance_matrix")]
pub mod distance_matrix;

#[cfg(feature = "elevation")]
pub mod elevation;

#[cfg(feature = "geocoding")]
pub mod geocoding;

#[cfg(any(feature = "autocomplete", feature = "places"))]
pub mod places;

#[cfg(feature = "reqwest-middleware")]
pub mod reqwest_maybe_middleware;

#[cfg(feature = "roads")]
pub mod roads;

#[cfg(feature = "time_zone")]
pub mod time_zone;

#[cfg(feature = "address_validation")]
pub mod address_validation;

#[cfg(feature = "places-new-core")]
pub mod places_new;

// -----------------------------------------------------------------------------
//
// Re-exports for the main event

pub use crate::{
    client::Client,
    error::Error,
    types::error::Error as TypeError,
};

#[deprecated(note = "use `google_maps::Client` instead", since = "3.8.0")]
pub use crate::client::Client as ClientSettings;

#[deprecated(note = "use `google_maps::Client` instead", since = "3.8.0")]
pub use crate::client::Client as GoogleMapsClient;

#[deprecated(note = "use `google_maps::Error` instead", since = "3.8.0")]
pub use crate::error::Error as GoogleMapsError;

// -----------------------------------------------------------------------------
//
// Re-exports for common shared types

#[cfg(any(feature = "geocoding", feature = "places"))]
pub use crate::types::address_component::AddressComponent;

#[cfg(any(
    feature = "directions",
    feature = "distance_matrix",
    feature = "geocoding",
    feature = "places"
))]
pub use crate::types::bounds::Bounds;

pub use crate::types::classified_error::ClassifiedError;

#[cfg(any(
    feature = "autocomplete",
    feature = "directions",
    feature = "geocoding"
))]
pub use crate::types::country::Country;

#[cfg(any(feature = "geocoding", feature = "places"))]
pub use crate::types::geometry::Geometry;

#[cfg(any(
    feature = "autocomplete",
    feature = "directions",
    feature = "distance_matrix",
    feature = "geocoding",
    feature = "places",
    feature = "time_zone"
))]
pub use crate::types::language::Language;

#[cfg(any(
    feature = "address_validation",
    feature = "autocomplete",
    feature = "directions",
    feature = "distance_matrix",
    feature = "elevation",
    feature = "geocoding",
    feature = "places",
    feature = "roads",
    feature = "time_zone"
))]
pub use crate::types::latlng::LatLng;

#[cfg(any(feature = "geocoding", feature = "places"))]
pub use crate::types::location_type::LocationType;

#[cfg(any(
    feature = "autocomplete",
    feature = "directions",
    feature = "distance_matrix",
    feature = "geocoding",
    feature = "places"
))]
pub use crate::types::place_type::PlaceType;

#[cfg(any(
    feature = "autocomplete",
    feature = "directions",
    feature = "distance_matrix",
    feature = "geocoding",
    feature = "places"
))]
pub use crate::types::region::Region;

// -----------------------------------------------------------------------------
//
// Re-exports for optional dependencies

#[cfg(feature = "reqwest")]
mod request_rate;

#[cfg(feature = "reqwest")]
pub use crate::request_rate::api::Api;

#[cfg(all(feature = "reqwest", feature = "reqwest-middleware"))]
type ReqError = reqwest_maybe_middleware::Error;

#[cfg(all(feature = "reqwest", not(feature = "reqwest-middleware")))]
type ReqError = reqwest::Error;