uiuifree_gmaps_geocoder/lib.rs
1//! Async Rust client for the [Google Maps Geocoding API][geocoding-api] — and nothing else.
2//!
3//! One endpoint (`/maps/api/geocode/json`), three lookups:
4//!
5//! | Lookup | Method |
6//! | --- | --- |
7//! | Address → coordinates (*forward geocoding*) | [`GeocodingClient::geocode`] |
8//! | Coordinates → address (*reverse geocoding*) | [`GeocodingClient::reverse_geocode`] |
9//! | Place ID → address and coordinates | [`GeocodingClient::geocode_place_id`] |
10//! | Any of the three, with options | [`GeocodeRequest`] passed to [`GeocodingClient::send`] |
11//!
12//! Results are typed ([`GeocodeResult`], [`LocationType`], [`GeocodeStatus`]), failures come
13//! back classified instead of retried, and the API key never reaches a log line.
14//!
15//! # Quick start
16//!
17//! ```no_run
18//! use uiuifree_gmaps_geocoder::GeocodingClient;
19//!
20//! #[tokio::main]
21//! async fn main() -> Result<(), uiuifree_gmaps_geocoder::Error> {
22//! let client = GeocodingClient::new(std::env::var("GOOGLE_MAPS_API_KEY").unwrap());
23//!
24//! // Address → coordinates
25//! for r in client.geocode("1600 Amphitheatre Parkway, Mountain View, CA").await? {
26//! let loc = r.location();
27//! println!("{} => {}, {}", r.formatted_address, loc.lat, loc.lng);
28//! }
29//!
30//! // Coordinates → address
31//! for r in client.reverse_geocode(35.6580, 139.6994).await? {
32//! println!("{}", r.formatted_address);
33//! }
34//! Ok(())
35//! }
36//! ```
37//!
38//! # Requests with options
39//!
40//! [`GeocodeRequest`] is a borrowing builder that covers every parameter the endpoint
41//! accepts: [`language`](GeocodeRequest::language), [`region`](GeocodeRequest::region),
42//! [`bounds`](GeocodeRequest::bounds), [`components`](GeocodeRequest::component),
43//! [`result_type`](GeocodeRequest::result_type),
44//! [`location_type`](GeocodeRequest::location_type) and
45//! [`extra_computations`](GeocodeRequest::address_descriptors).
46//!
47//! ```no_run
48//! # async fn run() -> Result<(), uiuifree_gmaps_geocoder::Error> {
49//! use uiuifree_gmaps_geocoder::{GeocodeRequest, GeocodingClient, LocationType};
50//!
51//! let client = GeocodingClient::new("YOUR_API_KEY");
52//!
53//! // Japanese defaults in one call: language=ja, region=jp, components=country:JP.
54//! let in_japan = client.send(GeocodeRequest::japan("東京都渋谷区渋谷2-24-12")).await?;
55//!
56//! // Reverse geocoding, narrowed to rooftop-accurate street addresses.
57//! let rooftop = client
58//! .send(
59//! GeocodeRequest::reverse(35.658, 139.6994)
60//! .result_type("street_address")
61//! .location_type(LocationType::Rooftop),
62//! )
63//! .await?;
64//! # let _ = (in_japan, rooftop);
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! # Reading a result
70//!
71//! Every field Google returns is on [`GeocodeResult`]; the common ones have helpers.
72//!
73//! ```
74//! use uiuifree_gmaps_geocoder::{most_precise, GeocodeResult};
75//!
76//! fn summarize(results: &[GeocodeResult]) {
77//! // Most accurate hit: ROOFTOP > RANGE_INTERPOLATED > GEOMETRIC_CENTER > APPROXIMATE.
78//! let Some(best) = most_precise(results) else {
79//! return; // ZERO_RESULTS: no match, and that is not an error
80//! };
81//! let loc = best.location();
82//! println!("{}, {}", loc.lat, loc.lng);
83//! println!("{:?} {:?}", best.prefecture(), best.locality());
84//! println!("{:?}", best.postal_code());
85//! println!("{:?}", best.component("route"));
86//!
87//! // Did we resolve to a building, or only to a city/postal-code centroid?
88//! if !best.geometry.location_type.is_street_level() {
89//! println!("approximate only: {}", best.geometry.location_type);
90//! }
91//! }
92//! ```
93//!
94//! # Errors
95//!
96//! | Google `status` / transport | This crate |
97//! | --- | --- |
98//! | `OK` | `Ok(results)` |
99//! | `ZERO_RESULTS` | `Ok(vec![])` — no match is not an error |
100//! | `OVER_QUERY_LIMIT`, `UNKNOWN_ERROR` | [`Error::Api`] — worth retrying |
101//! | HTTP 429/5xx, timeout, connection failure | [`Error::Http`] — worth retrying |
102//! | `REQUEST_DENIED`, `INVALID_REQUEST`, `OVER_DAILY_LIMIT` | [`Error::Api`] — retrying will not help |
103//!
104//! **This crate has no retry policy.** Every failure above reaches you on the first attempt:
105//! backoff, jitter, queueing and quota control belong to the caller, which is where the
106//! context to make those choices lives. [`Error::is_retryable`] classifies an error so you
107//! can drive that decision without matching on transport details yourself.
108//!
109//! One exception sits below this crate: `reqwest` replays a request the server refused at
110//! the protocol level (an HTTP/2 NACK) before processing it. That is transport plumbing,
111//! not a policy — nothing the server acted on is ever sent twice. Pass a client built with
112//! `reqwest::retry::never()` to [`GeocodingClient::with_http_client`] to turn even that off.
113//!
114//! The API key is stripped from every error ([`Error::Http`] carries no URL) and printed as
115//! `[REDACTED]` by `GeocodingClient`'s `Debug`, so errors are safe to log.
116//!
117//! # Deliberate omissions
118//!
119//! No retrying, no caching (Google allows at most 30 days anyway), no
120//! `extra_computations=BUILDING_AND_ENTRANCES`, and no other Google Maps Platform API.
121//! Quota, billing and request de-duplication stay with the caller.
122//!
123//! # Google Maps Platform terms
124//!
125//! Using this crate means calling Google's API under the [Maps Platform terms][terms]:
126//! geocoding results may be cached for at most 30 days (`place_id` may be stored),
127//! and displaying results generally requires a Google map and attribution. A library
128//! cannot enforce that for you.
129//!
130//! [geocoding-api]: https://developers.google.com/maps/documentation/geocoding/overview
131//! [terms]: https://cloud.google.com/maps-platform/terms
132#![forbid(unsafe_code)]
133#![warn(missing_docs, missing_debug_implementations)]
134mod client;
135mod error;
136mod model;
137mod types;
138
139pub use client::{GeocodeRequest, GeocodingClient};
140pub use error::Error;
141pub use model::{
142 most_precise, AddressComponent, Bounds, GeocodeResponse, GeocodeResult, Geometry, LatLng,
143 PlusCode,
144};
145pub use types::{Component, GeocodeStatus, LocationType};