google_maps

适用于Rust编程语言的非官方Google Maps平台客户端库。

该客户端目前实现了路线API、距离矩阵API、海拔API、地理编码API、时区API以及地点和道路API的部分功能。

安装

配置依赖项

[dependencies]
google_maps = "3.5"

可选地，添加 rust_decimal = "1" 和 rust_decimal_macros = "1" 以访问 dec! 宏。此宏可以用于在程序中定义十进制数字。

这对于将纬度和经度硬编码到代码中以进行测试很有用。

功能标志

可以通过功能标志分别启用所需的Google Maps API。

此外，支持使用rustls的Reqwest。

Google Maps客户端功能标志

• autocomplete ‧ 包含Google Maps地点自动完成API
• directions ‧ 包含Google Maps路线API
• distance_matrix ‧ 包含Google Maps距离矩阵API
• elevation ‧ 包含Google Maps海拔API
• geocoding ‧ 包含Google Maps地理编码API
• places ‧ 包含Google Maps地点API
• roads ‧ 包含Google Maps道路API
• time_zone ‧ 包含Google Maps时区API
• enable-reqwest ‧ 使用 reqwest 查询Google Maps API
• enable-reqwest-middleware ‧ 使用 reqwest-middleware 查询Google Maps API
• geo ‧ 支持rust geo生态系统
• polyline 允许轻松地将从 Route 或 Step 转换为 geo LineString

注意：autocomplete 功能涵盖了 Places API 自动补全相关的服务：Place Autocomplete 请求 和 Query Autocomplete 请求。所有其他 Places API 服务都由 places 功能覆盖。

reqwest 特性标志

仅适用于 enable-reqwest。

• native-tls
• rustls
• gzip
• brotli

默认特性标志

默认情况下，Google Maps 客户端包含所有实现的 Google Maps APIs。Reqwest 将使用系统本机 TLS（native-tls）来加密连接，并已启用 gzip 压缩（gzip）。

default = [
	# 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",
]

特性标志使用示例

此示例将仅包括 Google Maps Directions API。Reqwest 将使用 Rustls 库来加密连接，并已启用 brotli 压缩。

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

发行说明

完整的变更日志可在此处找到。

发行版本可在GitHub上找到。

示例

路线 API

路线 API 是一种计算地点之间路线的服务。您可以搜索包括公交、驾驶、步行或骑自行车在内的多种交通方式的路线。

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::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);

距离矩阵 API

距离矩阵 API 是一种提供起点和终点之间推荐路线的出行距离和时间的矩阵服务。

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::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);

海拔 API（位置性）

海拔 API 为地球上所有位置的地面（包括海底深度位置，返回负值）提供海拔数据。

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

地理编码 API

地理编码 API 是一种提供地址的地理编码和反向地理编码的服务。地理编码是将地址（如街道地址）转换为地理坐标（如纬度和经度）的过程，您可以使用这些坐标在地图上放置标记或将地图定位。

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

反向地理编码 API

地理编码 API 是一种提供地址的地理编码和反向地理编码的服务。反向地理编码是将地理坐标转换为人类可读地址的过程。

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(", ")
    );
}

时区 API

时区 API 为地球上表面的位置提供时间偏移数据。您请求特定纬度/经度对和日期的时间区信息。该 API 返回该时区的名称、从 UTC 的时间偏移量和夏令时偏移量。

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()
    );
}

地理位置 API

Google 的地理位置 API 似乎已离线。虽然在线文档仍然可用，并且 API 通过 Google Cloud Platform 控制台似乎可配置，但地理位置 API 对所有请求均响应状态码 404 Not Found 并返回空体。

控制请求设置

可以使用 Google Maps 客户端设置来更改请求速率和自动重试参数。

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();

反馈

我希望你在你的项目中取得成功！如果这个crate对你不起作用，或者它没有按你想象的方式工作，或者如果你有请求或建议——请向我报告！我可能不会很快响应，但我一定会回复。谢谢！

路线图

• 跟踪请求和请求元素以进行速率限制。
• 为所有API创建一个通用的get()函数。
• 尽可能将显式查询验证转换为会话类型。
• 地点API。仅部分实现。如果您希望实现任何缺失的部分，请与我联系。
• 道路API。仅部分实现。如果您希望实现任何缺失的部分，请与我联系。

作者注

这个crate预期将运行良好，并实现更多重要的Google Maps功能。它应该运行良好，因为serde和默认的reqwest做了大部分繁重的工作！

我创建了此客户端库，因为我需要一个项目中的几个Google Maps Platform功能。因此，我决定将我的库分离成一个公共crate。这是表示感激和回馈Rust社区的一种微小的象征。我希望它能节省某人一些工作。