腾讯地图 (TMap)

Feature: tmap | 依赖: reqwest, serde_json

📖 官方文档：https://lbs.qq.com/service/webService/webServiceGuide

简介

腾讯地图 Web 服务 API 封装，支持地理编码、逆地理编码、路径规划、POI 搜索、天气查询、IP 定位和坐标转换。

配置

[tmap]
key = "your_tencent_map_key"  # 腾讯地图 Web 服务 API Key (lbs.qq.com)

API

所有方法返回 Result<TmapResponse, afast::Error>。

#![allow(unused)]
fn main() {
// 配置自动从 config.toml 的 [tmap] 段加载
let app = AFaster::new("config.toml".to_string()).await.unwrap();
let tmap = &app.state.tmap;  // 在 handler 中通过 state.tmap 访问
}

TmapResponse

#![allow(unused)]
fn main() {
pub struct TmapResponse {
    pub status: i64,        // 0=成功
    pub message: String,    // "Success" 或错误描述
    pub request_id: String, // 请求唯一标识
    pub data: Value,        // 业务数据
}
}

• response.is_ok() — 快速判断是否成功

地址服务

#![allow(unused)]
fn main() {
// 地理编码: 地址 → 坐标
let res = tmap.geocoder("北京市海淀区彩和坊路海淀西大街74号", Some("北京")).await?;

// 逆地理编码: 坐标 → 地址
let res = tmap.reverse_geocoder("39.984154,116.307490", Some("1"), Some("address_format=short;radius=5000")).await?;
}

路径规划

#![allow(unused)]
fn main() {
// 驾车
let res = tmap.direction_driving("39.984154,116.307490", "39.904989,116.405285", None, Some("LEAST_TIME")).await?;

// 步行
let res = tmap.direction_walking("39.984154,116.307490", "39.904989,116.405285").await?;

// 骑行
let res = tmap.direction_bicycling("39.984154,116.307490", "39.904989,116.405285").await?;

// 电动车
let res = tmap.direction_ebicycling("39.984154,116.307490", "39.904989,116.405285").await?;

// 公交
let res = tmap.direction_transit("39.984154,116.307490", "39.904989,116.405285", Some("LEAST_TIME")).await?;

// 距离矩阵
let res = tmap.distance_matrix("driving", "39.984154,116.307490", "39.904989,116.405285;39.912345,116.387654").await?;
}

POI 搜索

#![allow(unused)]
fn main() {
// 周边搜索
let res = tmap.search("酒店", "nearby(39.984154,116.307490,1000)", Some("5"), Some("1")).await?;

// 城市搜索
let res = tmap.search("北京大学", "region(北京,0)", Some("5"), Some("1")).await?;

// 矩形搜索
let res = tmap.search("美食", "rectangle(39.907,116.368,39.914,116.379)", Some("5"), Some("1")).await?;

// 多边形搜索
let res = tmap.search_by_polygon("公园", "39.93,116.35;39.93,116.43;39.91,116.43;39.91,116.35", None, None).await?;

// 周边推荐（无需关键词）
let res = tmap.explore("nearby(39.984154,116.307490,1000)", Some("1")).await?;

// 关键词提示
let res = tmap.suggestion("北京大", Some("北京")).await?;

// POI 详情
let res = tmap.poi_detail("6621879543162709731").await?;
}

天气查询

#![allow(unused)]
fn main() {
// 实况天气（按 adcode）
let res = tmap.weather(Some("110000"), None, Some("now"), None).await?;

// 天气预报（含生活指数）
let res = tmap.weather(Some("110000"), None, Some("future"), Some("index")).await?;

// 逐小时预报（按坐标）
let res = tmap.weather(None, Some("39.984154,116.307490"), Some("hours"), None).await?;
}

IP 定位

#![allow(unused)]
fn main() {
let res = tmap.ip_location(Some("114.242.249.146")).await?;
}

坐标转换

#![allow(unused)]
fn main() {
// GPS(WGS-84) → 腾讯(GCJ-02)
let res = tmap.coord_translate("39.984154,116.307490", "1").await?;

// 百度(BD-09) → 腾讯(GCJ-02)
let res = tmap.coord_translate("39.984154,116.307490", "3").await?;
}

错误码

注意事项

• 坐标格式: 腾讯地图使用 纬度,经度 顺序（与高德的经度,纬度相反！）
• 坐标系: GCJ-02，GPS 原始坐标需先通过 coord_translate 转换
• 成功状态: status == 0（不同于高德的 status == "1"）
• 路线时长: 驾车 duration 单位为分钟，距离矩阵 duration 单位为秒
• 状态码详情: https://lbs.qq.com/service/webService/webServiceGuide/status

功能对比 (TMap vs AMap)