Skip to content

Latest commit

 

History

47 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

百度地图微信小程序JS API v2.1

相关链接

百度地图开放平台
百度地图微信小程序JSAPI服务

更新日志

  • 2017.01.11:发布 v1.0 版本,支持 search、suggestion、regeocoding 和 weather 四种接口。

  • 2017.02.15:修复 location 参数无效的 bug。

  • 2019.07.03:发布 v1.1 版本,增加 geocoding 接口,支持地址信息到经纬度的转换。

  • 2020.09:由于 ak 鉴权限制,小程序端 jsapi 暂不支持天气服务(已修复,详见 v2.0)。

  • 2026.08-09(v2.0):工程化重构与功能增强。

    • 工程:统一请求管线(定位 → 参数 → SN 签名 → 请求 → 错误码映射 → 回调)、 构建链(babel 转 ES5 + terser,产物输出 dist/ 与 demo/libs/)、 失败回调结构化字段(message / rawMessage,rawMessage 保留完整原文)、 坐标系自动适配(gcj02,公交自动换算百度坐标)、index.d.ts 完整类型声明。
    • 新增接口:路线规划(driving / walking / transit / riding)、 静态图(staticMap 全参数 + 取景联动)、海外天气(weatherAbroad)。
    • 天气修复:确认 weather/v1/ 路径末尾必须带斜杠(无斜杠返回 302), 小程序端天气服务可用(原 telematics 老接口已下线);国内/海外天气解析与演示完善。
    • 方法规范化:regeocoding → reverseGeocoding(旧名保留为兼容别名)。
    • Demo:产品化示例(周边探索、多方案路线规划、静态图取景、天气主题与国际城市切换等)。 ⚠️ 接口参数/返回值语义变化见各小节;request 域名 要求不变。
  • 2026.09(v2.1):Place API 全面升级 V3,移除 v2 检索路径。

    • search 升级:按入参自动分派 —— 传 region 走 /place/v3/region 城市检索(无需定位); 未传则走 /place/v3/around 周边检索(location 默认当前定位)。入参名与官方 V3 文档一致, 新增 tag / type / radius_limit / is_light_version / extensions_adcode / center 透传。
    • 行为变化:请求参数最小化——未传参数一律不携带,与官方文档一致(全接口:radius/page_size/page_num/ scope/output/tactics/extensions_road/extensions_town/language/language_auto 等,服务端按默认值处理); V3 排序策略更贴近百度地图 App 推荐。
    • 保留的必要默认值:output=json(地理编码/逆编码官方默认 XML,去掉无法解析)、extensions_poi=1 (官方默认 0,SDK 既有行为)、data_type=all(官方必填)、各坐标参数(gcj02 正确性必需)。
    • suggestion 注意:region 为必选参数(region/bounds/location 三选一),未传将由服务端返回参数错误。
    • suggestion 升级:/place/v3/suggestion;V3 返回字段为 results(复数),SDK 统一输出 result 保持契约; 返回元素不再包含 cityid(城市编码),可改用 city / adcode。
    • 移除 /place/v2/search 与 /place/v2/suggestion 路径(route/weather/staticMap 等无 V3 版本,保持不变)。

概述

百度地图微信小程序JavaScript API(下文简称小程序JSAPI),对百度地图Web服务API中的部分lbs接口,按照微信小程序的规范进行了前端JS封装,以方便微信小程序开发者的调用。

部分接口对返回的POI等数据按照微信小程序的数据格式进行了处理,可直接用于小程序的map中。

目前开放的小程序JSAPI接口和调用的WebAPI接口对应关系为:

小程序JSAPI Web服务API
search Place API V3(city 城市检索 /place/v3/region、周边检索 /place/v3/around)
suggestion Place Suggestion API
reverseGeocoding Geocoding API的逆地址解析部分(旧名 regeocoding 兼容)
geocoding Geocoding API的正地址解析部分
driving 路线规划 API 驾车(direction/v2/driving)
walking 路线规划 API 步行(direction/v2/walking)
transit 路线规划 API 公交(direction/v2/transit)
riding 路线规划 API 骑行(direction/v2/riding)
weather 天气服务(weather/v1/)
weatherAbroad 海外天气服务(weather_abroad/v1/)
staticMap 静态图服务(staticimage/v2)

快速开始

  1. 引入:将 dist/bmap-wx.min.js(发布产物,纯 ES5,可直接运行)复制到你的小程序目录:
const { BMapWX } = require('./libs/bmap-wx.min.js');
const bmap = new BMapWX({ ak: '你的AK' }); // 服务端 AK 可另传 sk,SDK 自动生成 SN 签名

// 周边检索(默认):中心点为当前定位或 location;城市检索传 region 即可,无需定位
bmap.search({
  query: '天安门',
  // region: '北京', // 传 region 走 /place/v3/region 城市检索(与 location 二选一)
  success(res) {
    console.log(res.wxMarkerData); // 小程序 map markers(gcj02),可直接用于 <map markers>
  },
  fail(err) {
    console.log(err.message, err.statusCode);
  },
});
  1. AK 申请:在百度地图开放平台控制台创建应用。开发调试优先用「微信小程序」类型 AK(绑定项目 AppID);若遇 220「APP Referer 校验失败」可改用服务端类型 AK(IP 白名单留空或配 SN 签名兜底,SK 填入 sk 字段)。
  2. 合法域名:正式发布前在小程序后台把 https://api.map.baidu.com 加入 request 合法域名(开发阶段可先在开发者工具中勾选"不校验合法域名")。
  3. 调用:方法均为回调式(success / fail),详见下方类参考;成功入参统一为 { originalData, ...规范字段 },失败入参为 { errMsg, message, statusCode, rawMessage }。

Demo

demo 目录为完整示例小程序,包含周边探索(explore)、周边检索、关键词联想、地理编码、逆地理编码、路线规划(多方案)、静态图(取景联动)、天气(国际城市切换)等页面。运行前复制 demo/config.example.js 为 demo/config.js 并填入你的 AK。

类参考

BMapWX

此类是小程序JSAPI的核心类。

构造函数:

构造函数 描述
BMapWX(options: Object) 创建 BMapWX 对象。options.ak 必填;可选 options.sk(服务密钥,配置后自动按官方《Web 服务 API 签名机制》生成 timestamp+sn,ak 保留且参与签名)与 options.serviceHost(自定义 API 域名,默认 https://api.map.baidu.com)

方法:

方法名 返回值 描述
getWXLocation(type, success, fail, complete) none 低级定位接口,默认返回 gcj02 坐标
search(searchParam: Object) none(结果经 success 回调) 进行search检索,检索周边POI信息
suggestion(suggestionParam: Object) none 进行suggestion检索,根据内容进行模糊检索匹配,输入补全
reverseGeocoding(reverseGeocodingParam: Object) none 逆地理编码,根据经纬度获得对应的地理描述信息
regeocoding 同上 @deprecated,同 reverseGeocoding(兼容旧调用)
geocoding(geocodingParam: Object) none 进行geocoding检索,根据地址获得对应的经纬度信息
driving(routeParam: Object) none 驾车路线规划(Web 服务 direction/v2/driving)
walking(routeParam: Object) none 步行路线规划(direction/v2/walking)
transit(routeParam: Object) none 公交(含地铁)路线规划(direction/v2/transit)
riding(routeParam: Object) none 骑行路线规划(direction/v2/riding)
weather(weatherParam: Object) none 国内天气查询
weatherAbroad(weatherParam: Object) none 海外天气查询
staticMap(staticMapParam: Object) none 生成静态图 URL(可直接用于 <image src>)

所有接口成功回调入参统一为 { originalData, ...规范字段 }:

  • 地图类接口(search / reverseGeocoding / geocoding)返回 wxMarkerData(小程序 marker 数组);
  • 路线类接口返回 routes(规范化方案数组,含 distance / duration / polyline / steps)与 wxPolylineData(主方案折线坐标,可直接用于小程序 <map polyline>);
  • 天气接口返回 weatherData 与 wxMarkerData(兼容旧版)。

失败回调统一为 { errMsg, message, statusCode, rawMessage }: errMsg 为展示用(后端原文,超长时截断 160 字符并加 …),message 为错误码映射的中文文案, statusCode 为百度状态码,rawMessage 为完整原文(未截断,供开发者诊断排查)。常用状态码文案:2 参数错误、 3 权限校验失败、4 配额校验失败、5 ak 不存在或非法、6 接口无访问权限、10 服务已下线、 220 Referer 校验失败(多因 AK 类型与应用来源不匹配)、221 IP 校验失败、 240 APP 服务被禁用(该服务未开通)、301 服务端错误、302 当日配额用完、 401 鉴权失败(ak 无效或 sn 校验不通过)、403 请求被拒绝。

routeParam: Object

路线规划(driving / walking / transit / riding)通用参数:
属性名 类型 是否必须 描述
origin string 是 起点,"纬度,经度" 或地点名称;名称形式部分接口需配合城市参数
destination string 是 终点,"纬度,经度" 或地点名称
tactics number 否 策略值,各交通方式不同(见官方 direction/v2 文档,默认 0)
ret_coordtype string 否 返回坐标类型,默认 gcj02(direction 系仅支持 gcj02 / bd09ll / wgs84)
coord_type string 否 输入坐标类型(driving / walking / riding),默认 gcj02(与小程序坐标系一致);公交接口不支持该参数,SDK 会对 gcj02 经纬度输入自动转换为百度坐标
transit 额外 string 否 region / region_d:起终点所在城市(如"北京市")
success Function(routeSuccess) 否 成功回调,入参 { originalData, routes, wxPolylineData }
fail Function 否 失败回调,入参 { errMsg, message, statusCode, rawMessage }

示例(driving / walking / transit / riding 用法相同):

bmap.driving({ // 换成 walking / transit / riding 即切换方式
  origin: '39.908823,116.397470', // "纬度,经度" 或地点名称
  destination: '39.915119,116.403963',
  success(res) {
    console.log(res.routes);          // 方案数组(多套方案时多条)
    console.log(res.wxPolylineData);  // 主方案折线(gcj02),用于 <map polyline>
  },
});

routeSuccess: Object

路线规划成功回调函数的参数
属性名 类型 是否必须 描述
originalData Object 是 direction/v2 接口返回的原始数据
routes Array 是 规划方案数组(百度返回多方案时多套,元素结构见下)
wxPolylineData Array 是 主方案(routes[0])折线坐标数组,元素为 { latitude, longitude }(gcj02),可直接用于 <map polyline> 的 points

routes 数组元素字段:

字段名 类型 描述
distance number 方案总距离(米)
duration number 方案总耗时(秒)
prefer string 方案偏好描述(如有)
polyline Array 本方案折线坐标,元素 { latitude, longitude }
steps Array 分步指引(含 path/road_name/instruction 等,结构随接口浮动,详情见官方 direction/v2 文档)

参数:

searchParam: Object

search() 按入参自动选择检索形态(`region` 与 `location` 二选一,对应两个官方接口):
search({ query, location })  // 周边检索 → /place/v3/around(location 缺省为当前定位,需定位授权)
search({ query, region })    // 城市检索 → /place/v3/region(无需定位;region 与 location 同时传时以 region 为准,SDK 不携带 location)

周边检索(/place/v3/around)参数

属性名 类型 是否必须 描述
query string 是 检索关键字(未传由服务端返回参数错误)
location string 否 中心点经纬度("纬度,经度"),默认当前定位点
radius number 否 检索半径(米);不传由服务端按默认值处理(官方默认 1000)
radius_limit string 否 是否严格限定在半径内('true'/'false')
tag string 否 检索分类偏好,与 query 组合(如 "美食")
type string 否 对 query 召回结果二次筛选(如 query=美食&type=火锅)
is_light_version string 否 'true' 优先检索速度;不传时排序更贴百度地图 App 推荐
extensions_adcode string 否 是否召回国标行政区划编码('true'/'false')
iconPath string 否 小程序marker图标
iconTapPath string 否 小程序点击后图标
width number 否 marker宽,新版基础库必填,未传时 SDK 默认 30
height number 否 marker高,新版基础库必填,未传时 SDK 默认 30
alpha number 否 marker透明度,默认为1
success Function(searchSuccess) 否 检索成功后回调回调函数
fail Function(searchFail) 否 检索失败后回调函数

城市检索(/place/v3/region)参数

属性名 类型 是否必须 描述
query string 是 检索关键字(未传由服务端返回参数错误)
region string 是 城市名/区县名
tag string 否 检索分类偏好,与 query 组合(如 "美食")
center string 否 距离排序基准点("纬度,经度",同 location 格式)
extensions_adcode string 否 是否召回国标行政区划编码('true'/'false')
iconPath string 否 小程序marker图标
iconTapPath string 否 小程序点击后图标
width number 否 marker宽,新版基础库必填,未传时 SDK 默认 30
height number 否 marker高,新版基础库必填,未传时 SDK 默认 30
alpha number 否 marker透明度,默认为1
success Function(searchSuccess) 否 检索成功后回调回调函数
fail Function(searchFail) 否 检索失败后回调函数

其余(分页 page_size/page_num、scope、output 等)与Place API V3一致,SDK 透传但未传不携带;已固定 ret_coordtype=gcj02ll,coord_type 默认 2(gcj02)。

searchSuccess: Object

search检索成功回调函数的参数
属性名 类型 是否必须 描述
wxMarkerData Array 是 小程序格式的marker对象数组,元素结构见下
originalData Object 是 Place API请求返回全部原始数据

wxMarkerData 数组元素字段(按微信 map markers 规范):

字段名 类型 描述
id number marker 序号(0 起)
title string POI 名称
latitude number 纬度(gcj02)
longitude number 经度(gcj02)
address string 地址
telephone string 电话

另透传调用方传入的 marker 样式字段:iconPath / iconTapPath / width / height / alpha 等。

searchFail: Object

search检索失败回调函数的参数
属性名 类型 是否必须 描述
errMsg string 是 错误信息(展示用,后端原文超长时截断 160 字符)
message string 是 错误码映射的中文文案
statusCode number 是 错误状态码
rawMessage string 是 完整原文(未截断,供诊断)

suggestionParam: Object

suggestion检索参数对象结构
属性名 类型 是否必须 描述
success Function(suggestionSuccess) 否 检索成功后回调函数
fail Function(suggestionFail) 否 检索失败后回调函数

其他参数和Place Suggestion API请求参数一致(V3 路径 /place/v3/suggestion;SDK 已固定 ret_coordtype=gcj02ll;location 可传排序参考点)。

示例:

bmap.suggestion({
  query: '天安门',
  region: '北京市',
  success(res) {
    console.log(res.result); // [{ name, address, city, district, location: { lat, lng }(gcj02) }]
  },
});

suggestionSuccess: Object

suggestion检索成功回调函数的参数
属性名 类型 是否必须 描述
originalData Object 是 Place Suggestion API请求返回全部原始数据
result Array 是 联想结果数组(从 originalData.result 读取的便捷字段),元素常见字段见下

result 数组元素常见字段:

字段名 类型 描述
name string 地点名称
address string 地址描述
city string 所属城市
district string 所属区县
location Object 经纬度 { lat, lng }(gcj02,SDK 已固定 ret_coordtype=gcj02ll,可直接用于小程序地图)
其余字段 - 与 Place Suggestion API 返回一致(如 uid、province、cityid 等),建议直接以 originalData 为准

suggestionFail: Object

suggestion检索失败回调函数的参数
属性名 类型 是否必须 描述
errMsg string 是 错误文案(展示用,后端原文超长时截断 160 字符)
message string 是 错误码映射的中文文案
statusCode number 是 错误状态码
rawMessage string 是 完整原文(未截断,供诊断)

reverseGeocodingParam: Object

reverseGeocoding检索参数对象结构(旧名 regeocoding 参数相同)
属性名 类型 是否必须 描述
location string 否 要解析的经纬度例如:39.915,116.404 默认值为当前定位点
iconPath string 否 小程序marker图标
iconTapPath string 否 小程序点击后图标
width number 否 marker宽,新版基础库必填,未传时 SDK 默认 30
height number 否 marker高,新版基础库必填,未传时 SDK 默认 30
alpha number 否 marker透明度,默认为1
success Function(regeocodingSuccess) 否 检索成功后回调函数
fail Function(regeocodingFail) 否 检索失败后回调函数

其他参数和Geocoding请求参数一致。

示例:

bmap.reverseGeocoding({
  location: '39.915,116.404', // "纬度,经度";默认当前定位
  success(res) {
    console.log(res.wxMarkerData[0].address); // 完整地址
  },
});

reverseGeocodingSuccess: Object

reverseGeocoding检索成功回调函数的参数
属性名 类型 是否必须 描述
wxMarkerData Array 是 小程序格式的marker对象数组,元素结构见下
originalData Object 是 Geocoding API请求返回全部原始数据

wxMarkerData 数组元素字段:

字段名 类型 描述
id number marker 序号(固定 0)
latitude number 纬度(gcj02)
longitude number 经度(gcj02)
address string 完整地址(formatted_address)
desc string 语义化描述(sematic_description)
business string 所在商圈

另透传调用方传入的 marker 样式字段:iconPath / iconTapPath / width / height / alpha 等。

reverseGeocodingFail: Object

reverseGeocoding检索失败回调函数的参数
属性名 类型 是否必须 描述
errMsg string 是 错误信息(展示用,后端原文超长时截断 160 字符)
message string 是 错误码映射的中文文案
statusCode number 是 错误状态码
rawMessage string 是 完整原文(未截断,供诊断)

geocodingParam: Object

geocoding检索参数对象结构
属性名 类型 是否必须 描述
address string 是 待解析地址,如"北京市海淀区上地十街10号"
ret_coordtype string 否 返回坐标类型,默认 gcj02ll(旧键 coordtype 兼容)
iconPath string 否 小程序marker图标
iconTapPath string 否 小程序点击后图标
width number 否 marker宽,新版基础库必填,未传时 SDK 默认 30
height number 否 marker高,新版基础库必填,未传时 SDK 默认 30
alpha number 否 marker透明度,默认为1
success Function(geocodingSuccess) 否 检索成功后回调函数
fail Function(geocodingFail) 否 检索失败后回调函数

其他参数和Geocoding请求参数一致。

示例:

bmap.geocoding({
  address: '北京市海淀区上地十街10号',
  success(res) {
    console.log(res.wxMarkerData[0]); // { latitude, longitude }(gcj02)
  },
});

geocodingSuccess: Object

geocoding检索成功回调函数的参数
属性名 类型 是否必须 描述
wxMarkerData Array 是 小程序格式的marker对象数组,元素结构见下
originalData Object 是 Geocoding API请求返回全部原始数据

wxMarkerData 数组元素字段:

字段名 类型 描述
id number marker 序号(固定 0)
latitude number 纬度(gcj02)
longitude number 经度(gcj02)

另透传调用方传入的 marker 样式字段:iconPath / iconTapPath / width / height / alpha 等。

geocodingFail: Object

geocoding检索失败回调函数的参数
属性名 类型 是否必须 描述
errMsg string 是 错误信息(展示用,后端原文超长时截断 160 字符)
message string 是 错误码映射的中文文案
statusCode number 是 错误状态码
rawMessage string 是 完整原文(未截断,供诊断)

weatherParam: Object

天气检索参数对象结构(weather 国内 / weatherAbroad 海外共用)
属性名 类型 是否必须 描述
location string 否 天气地点,"经度,纬度"(注意与其余接口顺序相反,天气接口约定;weatherAbroad 仅接受经纬度,不支持城市名);默认当前定位
district_id string 否 区域 ID(与 location 二选一,同时传时官方按 district_id 优先);不传按经纬度查询
data_type string 否 数据类型:all 实况+7天预报(默认)/ now 仅实况
output string 否 返回格式,默认 json
coordtype string 否 坐标类型,默认 gcj02
success Function(weatherSuccess) 否 成功回调,入参 { originalData, weatherData, wxMarkerData(兼容) }
fail Function(weatherFail) 否 失败回调,入参 { errMsg, message, statusCode, rawMessage }

示例:

bmap.weather({
  // location: '116.397470,39.908823', // "经度,纬度"(与其余接口顺序相反);默认当前定位
  success(res) {
    console.log(res.weatherData.currentCity, res.weatherData.temperature);
  },
});

// 海外天气:仅接受"经度,纬度",不支持城市名
bmap.weatherAbroad({
  location: '139.7671,35.6812', // 东京
  success: res => console.log(res.weatherData.currentCity),
});

weatherSuccess: Object

天气检索成功回调函数的参数
属性名 类型 描述
originalData Object 天气 API 返回的原始数据
weatherData Object 解析后的天气对象(字段见下)
wxMarkerData Array 兼容旧版:值为 [weatherData]

weatherData 字段:

字段名 类型 描述
country string 国家
province string 省份
currentCity string 城市
district string 区县(location.name,可能为空)
weatherDesc string 天气描述(如"多云")
temperature string 当前温度(摄氏度)
feelsLike number 体感温度(摄氏度)
humidity string 相对湿度(%)
aqi number 空气质量指数(data_type=now/all 时返回)
vis number 能见度(米)
forecast Array 7 天预报(data_type=all 时返回),元素含 date / week / textDay / high / low
windClass string 风力等级描述
windDir string 风向
updatedAt string 更新时间(接口原始格式,如 "20260903171500";demo 展示层已格式化,SDK 原样透传)

weatherFail: Object

天气检索失败回调函数的参数
属性名 类型 是否必须 描述
errMsg string 是 错误信息(展示用,后端原文超长时截断 160 字符)
message string 是 错误码映射的中文文案
statusCode number 是 错误状态码
rawMessage string 是 完整原文(未截断,供诊断)

staticMapParam: Object

静态图参数(本地拼装 URL,**不发起网络请求**;得到 url 后直接用于 <image src="..."> 组件)
属性名 类型 是否必须 描述
center string 否 中心点 "经度,纬度" 或地点名,默认北京
width / height number 否 图片宽高 px(默认 400×300;scale=2 时宽高 ≤512)
zoom number 否 地图级别 [3,19](scale=2 高清图上限 18),默认 11
scale 1|2 否 1 普通 / 2 高清(输出 2 倍像素;宽高 ≤512、zoom ≤18)
coordtype string 否 坐标类型,默认 gcj02ll(与小程序坐标系一致)
markers string 否 标注点坐标:"lng,lat|lng2,lat2"(多点用竖线 | 分隔),样式经 markerStyles(size,label,color)
labels string 否 标签坐标:"lng,lat"(仅坐标,多点用竖线 | 分隔),文字内容经 labelStyles(content,fontWeight,fontSize,fontColor,bgColor,border)
markerStyles string 否 标注点样式:size,label,color,多组用竖线 | 分隔,与 markers 一一对应
labelStyles string 否 标签样式:content,fontWeight,fontSize,fontColor,bgColor,border(content 为标签文字)
paths string 否 折线/多边形:多条折线用竖线 | 分隔,每条折线的点用分号 ; 分隔:"lng,lat;lng2,lat2|..."
pathStyles string 否 折线样式:color,weight,opacity[,fillColor],多组用竖线 | 分隔
copyright number|string 否 版权样式:0 log+文字 / 1 纯文字(默认 0)
bbox string 否 地图视野范围(与 center 二选一):"minX,minY;maxX,maxY"
dpiType string 否 ph(高清屏)/ pl(低分屏),自 V3 起已废弃(服务端不再区分,保留兼容)
success Function(staticMapSuccess) 否 成功回调,入参 { url, originalData }
fail Function 否 失败回调,入参 { errMsg, statusCode, message, rawMessage }

示例:

const bmap = new BMapWX({ ak });
bmap.staticMap({
  center: '116.397470,39.908823',
  labels: '116.397470,39.908823',
  labelStyles: '天安门,1,18,0x006600,0xFFFFFF,1',
  success: res => this.setData({ mapUrl: res.url }), // <image src="{{mapUrl}}">
});

staticMapSuccess: Object

静态图成功回调入参
属性名 类型 描述
url string 图片地址(https,含 ak/sn 校验参数)
originalData Object 生成的完整请求参数

About

百度地图微信小程序jsapi

Resources

Contributing

Stars

472 stars

Watchers

18 watching

Forks

Releases

Packages

Used by

Contributors

Languages