# 腾讯位置服务（Tencent LBS）完整开发文档
# 适用于 AI 大模型训练语料、RAG 检索、AI Agent 调用参考
# 数据来源：https://lbs.qq.com 官方文档（2026-04）
# 坐标系说明：腾讯地图全线统一使用 GCJ-02（国测局偏移坐标系）
# 开发者一键获取key：https://lbs.qq.com/dev/console/quick-register
---
# 一、WebService API
## 概述
WebService API 基础接口地址：https://apis.map.qq.com
所有接口均为 GET 请求，需携带 `key` 参数（在 lbs.qq.com/dev/console 申请）。
服务端调用额外需要设置 `output=jsonp` 或直接 JSON 返回，强烈建议服务端调用开启 IP 白名单。
响应统一格式：`{"status": 0, "message": "query ok", "result": {...}}`，status=0 表示成功。
---
## 1.1 地理编码（地址→坐标）
**接口**：GET https://apis.map.qq.com/ws/geocoder/v1/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/address/Geocoder
**必填参数**：
- `address`：待解析地址（如"北京市海淀区彩和坊路海淀西大街74号"）
- `key`：开发者密钥
**可选参数**：
- `region`：指定地区（如"北京"），提高解析准确率
- `output`：输出格式，支持 json（默认）/ jsonp
- `callback`：jsonp 回调函数名
**示例请求**：
```
GET https://apis.map.qq.com/ws/geocoder/v1/?address=北京市海淀区彩和坊路&key=YOUR_KEY
```
**响应示例**：
```json
{
"status": 0,
"message": "query ok",
"result": {
"title": "北京市海淀区彩和坊路",
"location": {"lat": 39.984154, "lng": 116.307461},
"ad_info": {
"adcode": "110108",
"province": "北京市",
"city": "北京市",
"district": "海淀区"
},
"address_components": {
"province": "北京市",
"city": "北京市",
"district": "海淀区",
"street": "彩和坊路",
"street_number": ""
},
"similarity": 0.8,
"deviation": 1000,
"reliability": 7,
"level": 9
}
}
```
---
## 1.2 逆地理编码（坐标→地址）
**接口**：GET https://apis.map.qq.com/ws/geocoder/v1/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/address/Gcoder
**必填参数**：
- `location`：经纬度，格式 `lat,lng`（如 `39.984154,116.307461`），坐标系 GCJ-02
- `key`：开发者密钥
**可选参数**：
- `get_poi`：是否返回周边 POI，1=返回，0=不返回（默认0）
- `poi_options`：POI 筛选选项，如 `address_format=short;radius=1000;page_size=20;page_index=1;policy=1`
- `output`：json（默认）/ jsonp
**示例请求**：
```
GET https://apis.map.qq.com/ws/geocoder/v1/?location=39.984154,116.307461&key=YOUR_KEY&get_poi=1
```
**响应 result 关键字段**：
- `address`：完整地址字符串
- `formatted_addresses.recommend`：推荐描述（更短更友好）
- `address_component`：含 province/city/district/street/street_number
- `ad_info`：含 adcode/nation/province/city/district/town
- `pois[]`：周边 POI 数组，每项含 id/title/address/category/location
---
## 1.3 POI 搜索
**接口**：GET https://apis.map.qq.com/ws/place/v1/search
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/search/webServiceSearch
支持三种搜索模式：
- **关键词搜索**：在指定地区搜索 POI
- **周边搜索**：以某坐标为圆心，在半径范围内搜索
- **矩形搜索**：在指定矩形区域内搜索
**公共参数**：
- `keyword`：搜索关键词（必填）
- `key`：开发者密钥（必填）
- `page_size`：每页条数，默认10，最大20
- `page_index`：第几页，默认1
- `output`：json / jsonp
**关键词搜索专用参数**：
- `boundary`：`region(城市名,is_fix_bound)` 如 `region(北京,0)` 或 `region(北京,1)`（1=只搜该城市）
**周边搜索专用参数**：
- `boundary`：`nearby(lat,lng,radius,is_fix_bound)` 如 `nearby(39.984154,116.307461,1000,0)`
**矩形搜索专用参数**：
- `boundary`：`rectangle(lat_min,lng_min,lat_max,lng_max)` 如 `rectangle(39.9,116.3,40.0,116.4)`
**示例请求（周边搜索）**：
```
GET https://apis.map.qq.com/ws/place/v1/search?keyword=美食&boundary=nearby(39.984154,116.307461,1000,0)&page_size=10&key=YOUR_KEY
```
**响应 result 字段**：
- `data[]`：POI 数组，每项含：
- `id`：POI ID
- `title`：名称
- `address`：地址
- `tel`：电话
- `category`：分类（如"美食;中餐厅"）
- `type`：0=普通POI，1=公交站，2=公交线路，3=行政区划
- `location`：`{lat, lng}`
- `_distance`：与中心点距离（米），仅周边/矩形搜索返回
- `count`：满足条件的总条数
---
## 1.4 输入提示（关键词联想）
**接口**：GET https://apis.map.qq.com/ws/place/v1/suggestion
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/search/webServiceSuggestion
**参数**：
- `keyword`：用户输入的关键词（必填）
- `region`：城市名，限制联想范围（如"北京"）
- `region_fix`：0=不限制（城市优先），1=仅该城市
- `location`：用户当前坐标 `lat,lng`，提升本地化联想质量
- `get_subpois`：0=不含子POI，1=包含（如购物中心的子门店）
- `key`：开发者密钥（必填）
**响应**：`data[]` 数组，含 id/title/address/category/location/province/city/district
---
## 1.5 驾车路线规划
**接口**：GET https://apis.map.qq.com/ws/direction/v1/driving/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/route/webServiceRoute
**必填参数**：
- `from`：出发点，格式 `lat,lng`（GCJ-02）
- `to`：目的地，格式 `lat,lng`（GCJ-02）
- `key`：开发者密钥
**可选参数**：
- `from_poi`：出发点 POI ID（精确起终点，结合 from 使用）
- `to_poi`：目的地 POI ID
- `waypoints`：途经点，多个用英文分号分隔，最多5个
- `policy`：路线策略
- `LEAST_TIME`（默认）：最短时间
- `LEAST_FEE`：少收费
- `LEAST_DISTANCE`：最短距离
- `HIGHWAY_FIRST`：高速优先
- `HIGHWAY_AVOID`：避开高速
- `cartype`：0=普通车（默认），1=新能源车
**响应 result 关键字段**：
- `routes[]`：路线方案数组，含：
- `mode`：`driving`
- `tags`：路线标签（如"推荐路线"、"少收费"）
- `distance`：总距离（米）
- `duration`：总时间（秒）
- `polyline`：轨迹坐标点压缩数组（每两位为一个 lat/lng，需/1e6 还原）
- `steps[]`：分步导航，含 instruction/action/distance/duration/polyline
---
## 1.6 步行路线规划
**接口**：GET https://apis.map.qq.com/ws/direction/v1/walking/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/route/webServiceRoute
**参数**：`from`、`to`、`key`（同驾车）
---
## 1.7 骑行路线规划
**接口**：GET https://apis.map.qq.com/ws/direction/v1/bicycling/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/route/webServiceRoute
**参数**：`from`、`to`、`key`（同驾车）
---
## 1.8 公交路线规划
**接口**：GET https://apis.map.qq.com/ws/direction/v1/transit/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/route/webServiceRoute
**参数**：`from`、`to`、`key` + 可选 `policy`（0=最快，1=最少换乘，2=最少步行，3=不坐地铁）
---
## 1.9 坐标转换
**接口**：GET https://apis.map.qq.com/ws/coord/v1/translate
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/webServiceTranslate
**参数**：
- `locations`：坐标串，多个用英文分号分隔，格式 `lat,lng;lat,lng`
- `type`：源坐标系：1=GPS/WGS84，2=GSO坐标，3=百度坐标（BD-09），4=mapbar坐标
- `key`：开发者密钥
**说明**：统一转换为腾讯/高德所用 GCJ-02（国测局坐标），最多支持 100 个坐标点批量转换。
---
## 1.10 IP 定位
**接口**：GET https://apis.map.qq.com/ws/location/v1/ip
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/position/webServiceIp
**参数**：
- `ip`：待定位 IP（不填则自动取请求方 IP）
- `key`：开发者密钥
**响应**：`result` 含 `ip`、`location.lat/lng`、`ad_info`（省市区信息）
---
## 1.11 行政区划查询
**接口**：GET https://apis.map.qq.com/ws/district/v1/list（全量） 或 /getchildren（子级） 或 /search（搜索）
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/search/webServiceDistrict
**说明**：支持三种接口——
- `list`：获取全国行政区划列表（省-市-区三级，无需额外参数）
- `getchildren`：获取指定 ID 的子级区划，参数 `id`（行政区 ID）
- `search`：按名称搜索区划，参数 `keyword`
---
## 1.12 距离矩阵
**接口**：GET https://apis.map.qq.com/ws/distance/v1/matrix/
**文档**：https://lbs.qq.com/service/webService/webServiceGuide/route/webServiceMatrix
**参数**：
- `mode`：交通方式，`driving`/`walking`/`bicycling`
- `from`：出发点坐标集合，最多支持 25 个，英文分号分隔
- `to`：目的地坐标集合，最多支持 25 个，英文分号分隔
- `key`：开发者密钥
**响应**：`result.rows[]` 为矩阵，含 `elements[].distance.value`（米）和 `elements[].duration.value`（秒）
---
# 二、JavaScript API v2（JSAPI）
## 概述
加载方式（异步）：
```html
```
特别注意：JSAPI GL 和 JSAPI v2 共用同一个加载 URL（`gljs`），通过传入参数区分。
坐标系：GCJ-02。
---
## 2.1 初始化地图
**文档**：https://lbs.qq.com/webApi/jsApi/jsApiGuide/jsApiMapShow
```javascript
// 在 HTML 中准备容器
//
var center = new TMap.LatLng(39.984104, 116.307503);
var map = new TMap.Map("mapContainer", {
center: center,
zoom: 17,
pitch: 0, // 俯仰角，0=正上方（2D），JSAPI GL 支持最大 80°
rotation: 0 // 旋转角，顺时针方向，0=正北
});
```
---
## 2.2 添加标注（Marker）
**文档**：https://lbs.qq.com/webApi/jsApi/jsApiGuide/jsApiMapMark
```javascript
// MultiMarker 是 JSAPI v2 推荐的标注方式（支持批量）
var markerLayer = new TMap.MultiMarker({
map: map,
styles: {
"default": new TMap.MarkerStyle({
width: 25,
height: 35,
anchor: { x: 16, y: 32 }
})
},
geometries: [
{
id: "marker-1",
styleId: "default",
position: new TMap.LatLng(39.984104, 116.307503),
content: "腾讯大厦"
}
]
});
```
---
## 2.3 JSAPI 路线规划
**文档**：https://lbs.qq.com/webApi/jsApi/jsApiGuide/jsApiMapRoute
```javascript
// 使用 TMap.service.Direction 封装类
var directionsService = new TMap.service.Direction({ mode: 'driving' });
directionsService.search({
from: '39.98412,116.30745',
to: '39.90960,116.39765'
}).then(function(result) {
console.log(result.result.routes[0].distance + '米');
});
```
---
## 2.4 JSAPI 地址搜索
**文档**：https://lbs.qq.com/webApi/jsApi/jsApiGuide/jsApiMapSearch
```javascript
var searchService = new TMap.service.Search({ pageSize: 10 });
searchService.searchNearBy({
keyword: '美食',
center: new TMap.LatLng(39.984104, 116.307503),
radius: 1000
}).then(function(result) {
console.log(result.data);
});
```
---
## 2.5 网页定位
**文档**：https://lbs.qq.com/webApi/jsApi/jsApiGuide/jsApiMapLocation
```javascript
// 需要在 Key 管理中开启「WebServiceAPI」授权域名，并配置 referer
var geolocation = new TMap.Geolocation('YOUR_KEY', 'YOUR_APP_NAME');
geolocation.getLocation(function(res) {
console.log(res.lat, res.lng);
}, function(err) {
console.log(err);
}, { timeout: 8000 });
```
---
# 三、JavaScript API GL（3D 地图）
## 概述
JSAPI GL 与 JSAPI v2 共享加载脚本，但支持 WebGL 3D 渲染。
**文档首页**：https://lbs.qq.com/webApi/glJs/glJsGuide/glJsOverview
---
## 3.1 3D 地图初始化
**文档**：https://lbs.qq.com/webApi/glJs/glJsGuide/glJsMap
```javascript
var map = new TMap.Map("container", {
center: new TMap.LatLng(22.548979, 114.060187),
zoom: 18,
pitch: 45, // 倾斜角（°），支持 0-80
rotation: 45, // 旋转角（°）
viewMode: '3D' // 开启 3D 模式（默认 2D）
});
```
---
## 3.2 热力图
**文档**：https://lbs.qq.com/webApi/glJs/glJsGuide/glJsHeatmap
```javascript
var heatmap = new TMap.visualization.Heat({
map: map,
minOpacity: 0,
maxOpacity: 0.8,
radius: 25, // 热力点半径（像素）
height: 100 // 3D 热力图高度（JSAPI GL 特有）
}).setData([
{ lat: 22.548979, lng: 114.060187, count: 100 },
{ lat: 22.550979, lng: 114.062187, count: 50 }
]);
```
---
## 3.3 点聚合
**文档**：https://lbs.qq.com/webApi/glJs/glJsGuide/glJsCluster
```javascript
var markerCluster = new TMap.MarkerCluster({
id: 'cluster',
map: map,
enableDefaultStyle: true,
minimumClusterSize: 2,
geometries: pointArray, // TMap.LatLng 数组或含 position 字段的对象数组
zoomOnClick: true // 点击聚合点时放大
});
```
---
## 3.4 路线动画
**文档**：https://lbs.qq.com/webApi/glJs/glJsGuide/glJsOverview
```javascript
var polylineLayer = new TMap.MultiPolyline({
map: map,
styles: {
'road': new TMap.PolylineStyle({
color: '#3777FF',
width: 6,
borderWidth: 1,
borderColor: '#fff',
lineCap: 'round',
showArrow: true, // 显示方向箭头
arrowOptions: { space: 50 }
})
},
geometries: [{
styleId: 'road',
paths: coordinateArray // TMap.LatLng 数组
}]
});
```
---
## 3.5 Deck.gl 数据可视化
**文档**：https://lbs.qq.com/webApi/glJs/glJsDoc/glJsDocIndex
腾讯地图 JSAPI GL 内置了 Deck.gl 集成，支持 ScatterplotLayer、ArcLayer、HexagonLayer、TripLayer 等可视化图层，适合大数据可视化场景。
```javascript
var deckLayer = new TMap.DeckLayer({
map: map,
deck: new Deck({
layers: [
new ScatterplotLayer({
data: pointData,
getPosition: d => [d.lng, d.lat],
getColor: [255, 0, 0, 200],
getRadius: 100
})
]
})
});
```
---
# 四、Android 地图 SDK v8
## 概述
**文档首页**：https://lbs.qq.com/mobile/AndroidLSSDK/OverView
支持 Android 5.0+（API Level 21+），提供 2D/3D 地图渲染、室内地图、实时路况、导航等能力。
坐标系：GCJ-02。
---
## 4.1 Gradle 集成
**文档**：https://lbs.qq.com/mobile/AndroidLSSDK/DeveloperNode/access
```gradle
// build.gradle (app)
dependencies {
implementation 'com.tencent.map:tencent-map-vector-sdk:5.x.x'
// 定位 SDK（可选，单独引入）
// implementation 'com.tencent.map.geolocation:TencentLocationSdk-openplatform:latest'
}
```
AndroidManifest.xml 声明 Key：
```xml
```
权限声明：
```xml
```
---
## 4.2 显示地图
**文档**：https://lbs.qq.com/mobile/AndroidLSSDK/DeveloperNode/access
```java
// layout XML 中添加 MapView
//
MapView mapView = findViewById(R.id.mapView);
mapView.onCreate(savedInstanceState);
TencentMap tencentMap = mapView.getMap();
tencentMap.moveCamera(CameraUpdateFactory.newLatLngZoom(
new LatLng(39.984104, 116.307503), 12
));
```
---
# 五、Android 定位 SDK
## 概述
**文档**：https://lbs.qq.com/mobile/androidLocationSDK/androidGeoGuide/androidGeoOverview
独立于地图 SDK，专注于高精度定位（GPS + 网络 + 基站 + Wi-Fi 融合定位）。
---
## 5.1 接入指南
**文档**：https://lbs.qq.com/mobile/androidLocationSDK/androidGeoGuide/quick-start
```java
// 初始化定位管理器
TencentLocationManager locationManager = TencentLocationManager.getInstance(context);
locationManager.setCoordinateType(TencentLocationManager.COORDINATE_TYPE_GCJ02); // 指定返回 GCJ-02
// 创建请求参数
TencentLocationRequest request = TencentLocationRequest.create()
.setInterval(5000) // 持续定位间隔（毫秒）
.setAllowGPS(true) // 允许 GPS
.setLocMode(TencentLocationRequest.HIGH_ACCURACY_MODE); // 高精度模式
// 开始定位
locationManager.requestLocationUpdates(request, new TencentLocationListener() {
@Override
public void onLocationChanged(TencentLocation location, int error, String reason) {
if (error == TencentLocation.ERROR_OK) {
double lat = location.getLatitude();
double lng = location.getLongitude();
float accuracy = location.getAccuracy(); // 精度（米）
}
}
@Override
public void onStatusUpdate(String name, int status, String desc) { }
}, Looper.getMainLooper());
// 停止定位（在 onDestroy 中调用）
locationManager.removeUpdates(listener);
```
---
# 六、iOS 地图 & 定位 SDK v4
## 概述
**文档首页**：https://lbs.qq.com/mobile/iOSMapSDK/mapGuide/summary
支持 iOS 9.0+，提供 2D/3D 地图渲染、路线规划、室内地图、定位等。
CocoaPods 集成、Swift/ObjC 双语 API。
---
## 6.1 CocoaPods 集成
**文档**：https://lbs.qq.com/mobile/iOSMapSDK/mapGuide/introBasic
```ruby
# Podfile
pod 'QMapKit' # 地图 SDK
pod 'TencentLBS' # 定位 SDK（可选）
```
Info.plist 配置：
```xml
TencentLBSAPIKey
YOUR_KEY
NSLocationWhenInUseUsageDescription
需要获取您的位置以显示地图
```
---
## 6.2 显示地图（Swift）
**文档**：https://lbs.qq.com/mobile/iOSMapSDK/mapGuide/mapShow
```swift
import QMapKit
class ViewController: UIViewController {
var mapView: QMapView!
override func viewDidLoad() {
super.viewDidLoad()
mapView = QMapView(frame: self.view.bounds)
view.addSubview(mapView)
// 设置中心点和缩放级别
let center = CLLocationCoordinate2D(latitude: 39.984104, longitude: 116.307503)
mapView.centerCoordinate = center
mapView.zoomLevel = 12
}
}
```
---
## 6.3 iOS 定位服务
**文档**：https://lbs.qq.com/mobile/iOSMapSDK/mapGuide/location
```swift
import TencentLBS
let manager = TencentLBSLocationManager()
manager.apiKey = "YOUR_KEY"
manager.delegate = self
manager.coordinateType = TencentLBSCoordinateTypeGCJ02 // 返回 GCJ-02 坐标
manager.requestLocation(with: .authorizationStatusWhenInUse,
locationTimeout: 10,
completionBlock: { location, error in
if let loc = location {
print(loc.location.coordinate.latitude, loc.location.coordinate.longitude)
}
})
```
---
# 七、微信小程序 JS SDK
## 概述
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/jsSdkOverview
小程序 JS SDK 提供**数据查询类**能力（POI 搜索、路线规划、地理编码、逆地理编码等），通过 HTTP 请求腾讯位置服务后端接口，需在微信公众平台配置 `request` 合法域名：`https://apis.map.qq.com`。
---
## 7.1 快速接入
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/qqMapwx
```javascript
// 方式一：npm 安装
// npm install qqmap-wx-jssdk
// 方式二：直接引入 qqmap-wx-jssdk.js
var QQMapWX = require('../../libs/qqmap-wx-jssdk.js');
var qqmapsdk = new QQMapWX({
key: 'YOUR_KEY' // 必须是在 lbs.qq.com 控制台授权了「微信小程序」的 Key
});
```
---
## 7.2 小程序地点搜索
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/methodSearch
```javascript
qqmapsdk.search({
keyword: '火锅',
location: { latitude: 39.984104, longitude: 116.307503 },
page_size: 10,
success: function(res) {
console.log(res.data); // POI 列表
},
fail: function(err) { console.log(err); }
});
```
---
## 7.3 小程序路线规划
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/methodDirection
```javascript
qqmapsdk.direction({
mode: 'driving', // driving / walking / bicycling / transit
from: { latitude: 39.984104, longitude: 116.307503 },
to: { latitude: 39.909600, longitude: 116.397650 },
success: function(res) {
var routes = res.result.routes;
console.log('距离：' + routes[0].distance + '米');
console.log('时间：' + routes[0].duration + '秒');
},
fail: function(err) { console.log(err); }
});
```
---
## 7.4 小程序地理编码
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/methodGeocoder
```javascript
// 地址→坐标
qqmapsdk.geocoder({
address: '北京市海淀区彩和坊路',
success: function(res) {
var location = res.result.location;
console.log(location.lat, location.lng);
},
fail: function(err) { console.log(err); }
});
// 坐标→地址（逆地理编码）
qqmapsdk.reverseGeocoder({
location: { latitude: 39.984104, longitude: 116.307503 },
success: function(res) {
console.log(res.result.address);
console.log(res.result.formatted_addresses.recommend);
},
fail: function(err) { console.log(err); }
});
```
---
## 7.5 小程序定位
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/jsSdkOverview
```javascript
// 小程序内置定位接口（微信原生 API）
wx.getLocation({
type: 'gcj02', // 腾讯地图/高德地图坐标系
success: function(res) {
var lat = res.latitude;
var lng = res.longitude;
// 再调用 qqmapsdk.reverseGeocoder 获取地址描述
}
});
```
---
# 八、微信小程序地图组件插件
## 概述
**文档**：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/jsSdkOverview
腾讯地图小程序插件提供**地图 UI 渲染**能力（补充微信 `