腾讯地图API对接文档

一、基础信息

1.1 服务商信息

官网: https://lbs.qq.com/
控制台: https://lbs.qq.com/console/mykey.html
开发文档: https://lbs.qq.com/webDevelop/index

1.2 已有密钥

Key: PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

1.3 API类型

WebService API（服务端调用）
JavaScript API（前端调用）
微信小程序 SDK

二、核心API

2.1 地点搜索（POI搜索）

接口地址

GET https://apis.map.qq.com/ws/place/v1/search

请求参数

参数	类型	必填	说明
keyword	String	是	搜索关键词
boundary	String	是	限定范围
page_size	Int	否	每页数量，默认10，最大20
page_index	Int	否	页码，默认1
key	String	是	API密钥

boundary参数说明

区域搜索

boundary=region(青岛市北区,0)
// 格式：region(city,auto_extend)
// city: 城市名称
// auto_extend: 0-不扩大范围, 1-扩大范围

矩形范围搜索

boundary=rectangle(36.05,120.30,36.15,120.45)
// 格式：rectangle(lat1,lng1,lat2,lng2)
// lat1,lng1: 西南角坐标
// lat2,lng2: 东北角坐标

圆形范围搜索

boundary=nearby(36.10,120.40,1000)
// 格式：nearby(lat,lng,radius)
// lat,lng: 圆心坐标
// radius: 半径（米），最大10000

请求示例

搜索小区

GET https://apis.map.qq.com/ws/place/v1/search
  ?keyword=金隅和府
  &boundary=region(青岛市北区,0)
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

搜索商圈

GET https://apis.map.qq.com/ws/place/v1/search
  ?keyword=商圈
  &boundary=region(北京,0)
  &page_size=20
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

响应示例

json

{
  "status": 0,
  "message": "query ok",
  "count": 2,
  "data": [
    {
      "id": "4719456223699704475",
      "title": "金隅和府",
      "address": "青岛市市北区新都心商圈",
      "category": "房地产:住宅区",
      "location": {
        "lat": 36.108100,
        "lng": 120.403700
      },
      "tel": "0532-12345678",
      "distance": 0
    },
    {
      "id": "xxx",
      "title": "新都心商圈",
      "address": "青岛市市北区",
      "category": "购物:商业街",
      "location": {
        "lat": 36.110000,
        "lng": 120.405000
      }
    }
  ]
}

状态码说明

status	说明
0	请求成功
311	Key格式错误
310	请求参数信息有误
306	请求有护持信息请检查字符串

2.2 关键词输入提示

接口地址

GET https://apis.map.qq.com/ws/place/v1/suggestion

请求参数

参数	类型	必填	说明
keyword	String	是	用户输入的关键词
region	String	是	限定城市
region_fix	Int	否	是否固定在city内，1-固定，0-不固定
key	String	是	API密钥

请求示例

GET https://apis.map.qq.com/ws/place/v1/suggestion
  ?keyword=金隅
  &region=青岛
  &region_fix=1
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

响应示例

json

{
  "status": 0,
  "message": "query ok",
  "count": 5,
  "data": [
    {
      "id": "xxx",
      "title": "金隅和府",
      "address": "青岛市市北区新都心商圈",
      "category": "房地产:住宅区",
      "location": {
        "lat": 36.108100,
        "lng": 120.403700
      },
      "adcode": 370203,
      "province": "山东省",
      "city": "青岛市",
      "district": "市北区"
    }
  ]
}

2.3 周边搜索

接口地址

GET https://apis.map.qq.com/ws/place/v1/search

请求示例

搜索地铁站

GET https://apis.map.qq.com/ws/place/v1/search
  ?keyword=地铁站
  &boundary=nearby(36.108100,120.403700,1000)
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

搜索学校

GET https://apis.map.qq.com/ws/place/v1/search
  ?keyword=学校
  &boundary=nearby(36.108100,120.403700,1000)
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

搜索医院

GET https://apis.map.qq.com/ws/place/v1/search
  ?keyword=医院
  &boundary=nearby(36.108100,120.403700,1000)
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

响应示例

json

{
  "status": 0,
  "message": "query ok",
  "count": 3,
  "data": [
    {
      "id": "xxx",
      "title": "3号线五四广场站",
      "address": "青岛市市南区",
      "category": "交通设施:地铁站",
      "location": {
        "lat": 36.108500,
        "lng": 120.404200
      },
      "distance": 500
    }
  ]
}

2.4 逆地址解析（坐标位置描述）

接口地址

GET https://apis.map.qq.com/ws/geocoder/v1/

请求参数

参数	类型	必填	说明
location	String	是	坐标位置（纬度,经度）
get_poi	Int	否	是否返回周边POI，1-返回，0-不返回
key	String	是	API密钥

请求示例

GET https://apis.map.qq.com/ws/geocoder/v1/
  ?location=36.108100,120.403700
  &get_poi=1
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

响应示例

json

{
  "status": 0,
  "message": "query ok",
  "result": {
    "location": {
      "lat": 36.108100,
      "lng": 120.403700
    },
    "address": "山东省青岛市市北区新都心商圈金隅和府",
    "formatted_addresses": {
      "recommend": "市北区金隅和府",
      "rough": "市北区金隅和府附近"
    },
    "address_component": {
      "nation": "中国",
      "province": "山东省",
      "city": "青岛市",
      "district": "市北区",
      "street": "新都心路",
      "street_number": "123号"
    },
    "ad_info": {
      "nation_code": "156",
      "adcode": "370203",
      "city_code": "370200",
      "name": "中国,山东省,青岛市,市北区",
      "location": {
        "lat": 36.108100,
        "lng": 120.403700
      },
      "nation": "中国",
      "province": "山东省",
      "city": "青岛市",
      "district": "市北区"
    },
    "poi": [
      {
        "id": "xxx",
        "title": "金隅和府",
        "category": "房地产:住宅区",
        "distance": 0
      }
    ]
  }
}

2.5 地址解析（地址转坐标）

接口地址

GET https://apis.map.qq.com/ws/geocoder/v1/

请求参数

参数	类型	必填	说明
address	String	是	地址（最多60个字符）
region	String	否	限定城市
key	String	是	API密钥

请求示例

GET https://apis.map.qq.com/ws/geocoder/v1/
  ?address=青岛市市北区金隅和府
  &key=PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2

响应示例

json

{
  "status": 0,
  "message": "query ok",
  "result": {
    "title": "金隅和府",
    "location": {
      "lat": 36.108100,
      "lng": 120.403700
    },
    "comprehension": {
      "name": "金隅和府"
    },
    "reliability": 7,
    "level": 11
  }
}

三、小程序SDK

3.1 引入SDK

下载SDKhttps://mapapi.qq.com/web/miniprogram/JSSDK/qqmap-wx-jssdk.min.js

pages.json配置

json

{
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序定位"
    }
  }
}

引入SDK

javascript

// utils/map.js
import QQMapWX from '@/utils/qqmap-wx-jssdk.min.js';

const qqmapsdk = new QQMapWX({
  key: 'PVZBZ-DB46Z-WFEXI-ZCKQA-HZBWS-BLBF2'
});

export default qqmapsdk;

3.2 小程序地图组件

地图找房页面

vue

<template>
  <view class="map-page">
    <!-- 地图组件 -->
    <map
      id="map"
      :latitude="mapCenter.lat"
      :longitude="mapCenter.lng"
      :scale="14"
      :markers="markers"
      @markertap="onMarkerTap"
      style="width: 100%; height: 60vh;"
    />
    
    <!-- 商圈筛选 -->
    <view class="district-filter">
      <scroll-view scroll-x>
        <view class="district-item"
              v-for="item in districts"
              :key="item.id"
              :class="{active: selectedDistricts.includes(item.id)}"
              @click="toggleDistrict(item)">
          {{ item.name }}
        </view>
      </scroll-view>
    </view>
    
    <!-- 小区列表抽屉 -->
    <view class="drawer">
      <view class="community-list">
        <view class="community-item"
              v-for="item in communities"
              :key="item.id"
              @click="viewCommunity(item)">
          <view class="name">{{ item.name }}</view>
          <view class="count">{{ item.property_count }}套房源</view>
        </view>
      </view>
    </view>
  </view>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import qqmapsdk from '@/utils/map.js';

const mapCenter = ref({
  lat: 36.108100,
  lng: 120.403700
});

const markers = ref([]);
const districts = ref([]);
const selectedDistricts = ref([]);
const communities = ref([]);

// 加载商圈列表
const loadDistricts = async () => {
  // 调用后端接口获取商圈列表
};

// 加载小区点位
const loadCommunities = async () => {
  // 根据选中的商圈加载小区
  // 生成markers数据
  markers.value = communities.value.map(item => ({
    id: item.id,
    latitude: item.lat,
    longitude: item.lng,
    iconPath: '/static/icons/marker.png',
    width: 30,
    height: 30,
    callout: {
      content: `${item.name}\n${item.property_count}套`,
      color: '#333',
      fontSize: 12,
      borderRadius: 5,
      padding: 5,
      display: 'ALWAYS'
    }
  }));
};

// 点击标记
const onMarkerTap = (e) => {
  const markerId = e.detail.markerId;
  const community = communities.value.find(item => item.id === markerId);
  // 跳转到小区房源列表
  uni.navigateTo({
    url: `/pages/property/list?community_id=${community.id}`
  });
};

onMounted(() => {
  loadDistricts();
  loadCommunities();
});
</script>

3.3 获取当前位置

javascript

// 获取用户位置
uni.getLocation({
  type: 'gcj02',
  success: (res) => {
    const lat = res.latitude;
    const lng = res.longitude;
    
    // 逆地址解析
    qqmapsdk.reverseGeocoder({
      location: {
        latitude: lat,
        longitude: lng
      },
      success: (res) => {
        console.log('当前位置：', res.result.address);
      }
    });
  }
});

3.4 搜索小区

javascript

// 搜索小区
qqmapsdk.search({
  keyword: '金隅和府',
  region: '青岛',
  success: (res) => {
    const pois = res.data;
    // 显示搜索结果
  }
});

3.5 路线规划

javascript

// 获取从A到B的路线
qqmapsdk.direction({
  mode: 'driving',    // driving-驾车, walking-步行, bicycling-骑行, transit-公交
  from: '36.10,120.40',
  to: '36.11,120.41',
  success: (res) => {
    const routes = res.result.routes;
    // 显示路线
  }
});

四、服务端调用示例

4.1 MapService.php

php

namespace app\service;

use think\facade\Cache;
use think\facade\Http;

class MapService
{
    private $key;
    private $apiUrl = 'https://apis.map.qq.com';
    
    public function __construct()
    {
        $this->key = config('map.tencent_key');
    }
    
    /**
     * POI搜索
     */
    public function searchPoi($keyword, $region = '青岛市北区')
    {
        $cacheKey = 'map_poi_' . md5($keyword . $region);
        
        return Cache::remember($cacheKey, function() use ($keyword, $region) {
            $response = Http::get($this->apiUrl . '/ws/place/v1/search', [
                'keyword' => $keyword,
                'boundary' => 'region(' . $region . ',0)',
                'page_size' => 20,
                'key' => $this->key
            ]);
            
            $result = $response->json();
            
            if ($result['status'] === 0) {
                return $result['data'];
            }
            
            return [];
        }, 300);    // 缓存5分钟
    }
    
    /**
     * 搜索商圈
     */
    public function searchDistricts()
    {
        $cacheKey = 'map_districts_qingdao';
        
        return Cache::remember($cacheKey, function() {
            $response = Http::get($this->apiUrl . '/ws/place/v1/search', [
                'keyword' => '商圈',
                'boundary' => 'region(青岛市北区,0)',
                'page_size' => 20,
                'key' => $this->key
            ]);
            
            $result = $response->json();
            
            if ($result['status'] === 0) {
                return array_map(function($item) {
                    return [
                        'name' => $item['title'],
                        'address' => $item['address'],
                        'lat' => $item['location']['lat'],
                        'lng' => $item['location']['lng'],
                        'poi_id' => $item['id']
                    ];
                }, $result['data']);
            }
            
            return [];
        }, 86400);    // 缓存1天
    }
    
    /**
     * 周边搜索
     */
    public function searchNearby($lat, $lng, $keyword, $radius = 1000)
    {
        $cacheKey = 'map_nearby_' . md5("{$lat},{$lng},{$keyword},{$radius}");
        
        return Cache::remember($cacheKey, function() use ($lat, $lng, $keyword, $radius) {
            $response = Http::get($this->apiUrl . '/ws/place/v1/search', [
                'keyword' => $keyword,
                'boundary' => "nearby({$lat},{$lng},{$radius})",
                'key' => $this->key
            ]);
            
            $result = $response->json();
            
            if ($result['status'] === 0) {
                return array_map(function($item) {
                    return [
                        'name' => $item['title'],
                        'address' => $item['address'],
                        'category' => $item['category'],
                        'distance' => $item['distance'],
                        'lat' => $item['location']['lat'],
                        'lng' => $item['location']['lng']
                    ];
                }, $result['data']);
            }
            
            return [];
        }, 300);
    }
    
    /**
     * 获取小区周边配套
     */
    public function getCommunityFacilities($lat, $lng)
    {
        $facilities = [];
        
        // 地铁站
        $facilities['subway'] = $this->searchNearby($lat, $lng, '地铁站', 1000);
        
        // 公交站
        $facilities['bus'] = $this->searchNearby($lat, $lng, '公交站', 500);
        
        // 学校
        $facilities['school'] = $this->searchNearby($lat, $lng, '学校', 1000);
        
        // 医院
        $facilities['hospital'] = $this->searchNearby($lat, $lng, '医院', 1000);
        
        // 商场
        $facilities['shopping'] = $this->searchNearby($lat, $lng, '商场', 1000);
        
        // 银行
        $facilities['bank'] = $this->searchNearby($lat, $lng, '银行', 500);
        
        return $facilities;
    }
    
    /**
     * 逆地址解析
     */
    public function reverseGeocode($lat, $lng)
    {
        $response = Http::get($this->apiUrl . '/ws/geocoder/v1/', [
            'location' => "{$lat},{$lng}",
            'get_poi' => 1,
            'key' => $this->key
        ]);
        
        $result = $response->json();
        
        if ($result['status'] === 0) {
            return $result['result'];
        }
        
        return null;
    }
}

五、配额与限制

5.1 每日配额

个人开发者：10,000次/天
企业开发者：100,000次/天

5.2 并发限制

单个Key：5次/秒
单个IP：10次/秒

5.3 建议

使用缓存减少API调用
合理设置缓存时间
POI数据缓存5-30分钟
商圈数据缓存1天

六、常见问题

6.1 为什么搜不到商圈？

腾讯地图商圈数据不全
建议搜索关键词："商业街"、"CBD"、"商圈"
需人工审核筛选结果

6.2 坐标系说明

腾讯地图使用：GCJ-02坐标系（火星坐标）
GPS原始坐标：WGS-84
需要转换时使用腾讯提供的转换API

6.3 小程序地图组件限制

同一页面最多1个地图组件
markers最多显示1000个
部分Android设备性能较差

文档版本：v1.0
更新日期：2025年11月3日
官方文档：https://lbs.qq.com/webDevelop/index

腾讯地图API对接文档 ​

一、基础信息 ​

1.1 服务商信息 ​

1.2 已有密钥 ​

1.3 API类型 ​

二、核心API ​

2.1 地点搜索（POI搜索） ​

接口地址 ​

请求参数 ​

boundary参数说明 ​

请求示例 ​

响应示例 ​

状态码说明 ​

2.2 关键词输入提示 ​

接口地址 ​

请求参数 ​

请求示例 ​

响应示例 ​

2.3 周边搜索 ​

接口地址 ​

请求示例 ​

响应示例 ​

2.4 逆地址解析（坐标位置描述） ​

接口地址 ​

请求参数 ​

请求示例 ​

响应示例 ​

2.5 地址解析（地址转坐标） ​

接口地址 ​

请求参数 ​

请求示例 ​

响应示例 ​

三、小程序SDK ​

3.1 引入SDK ​

3.2 小程序地图组件 ​

3.3 获取当前位置 ​

3.4 搜索小区 ​

3.5 路线规划 ​

四、服务端调用示例 ​

4.1 MapService.php ​

五、配额与限制 ​

5.1 每日配额 ​

5.2 并发限制 ​

5.3 建议 ​

六、常见问题 ​

6.1 为什么搜不到商圈？ ​

6.2 坐标系说明 ​

6.3 小程序地图组件限制 ​

腾讯地图API对接文档

一、基础信息

1.1 服务商信息

1.2 已有密钥

1.3 API类型

二、核心API

2.1 地点搜索（POI搜索）

接口地址

请求参数

boundary参数说明

请求示例

响应示例

状态码说明

2.2 关键词输入提示

接口地址

请求参数

请求示例

响应示例

2.3 周边搜索

接口地址

请求示例

响应示例

2.4 逆地址解析（坐标位置描述）

接口地址

请求参数

请求示例

响应示例

2.5 地址解析（地址转坐标）

接口地址

请求参数

请求示例

响应示例

三、小程序SDK

3.1 引入SDK

3.2 小程序地图组件

3.3 获取当前位置

3.4 搜索小区

3.5 路线规划

四、服务端调用示例

4.1 MapService.php

五、配额与限制

5.1 每日配额

5.2 并发限制

5.3 建议

六、常见问题

6.1 为什么搜不到商圈？

6.2 坐标系说明

6.3 小程序地图组件限制