一、产品概述重新定义 H5 定位开发体验维智科技正式发布JS-API 定位插件专为 H5 页面开发者打造轻量化定位搜索解决方案。无需复杂环境配置只需引入单个 JS 文件即可快速集成定位获取、正地理编码、逆地理编码、POI 搜索四大核心能力覆盖从设备定位到场景化搜索的全流程需求。插件兼容主流浏览器支持浏览器原生定位、IP 定位等多种方式内置智能错误处理机制让开发者专注业务逻辑无需关心底层实现细节。二、核心功能优势四大能力构建全域定位生态1. 多模定位引擎精准捕获设备位置智能定位策略优先使用浏览器原生定位GPS/Wi-Fi/ 基站失败时自动回退至 IP 定位支持离线环境下的 IP 粗定位定位成功率提升 30%。快速响应内置 5 秒超时机制超时后自动触发 IP 定位避免用户长时间等待支持缓存最近 2 分钟定位结果重复请求响应速度提升 50%。隐私合规严格遵循浏览器定位权限机制支持用户授权引导符合 GDPR、《个人信息保护法》等合规要求。2. 地理编码双引擎地址与坐标双向互通正地理编码输入标准化地址如 “湖北省武汉市洪山区泛悦城”返回精准经纬度坐标支持城市限定如 “武汉市”解决同名地址歧义问题地址解析准确率达 98%。逆地理编码输入经纬度对象{latitude: 30.5234, longitude: 114.3456}返回结构化地址信息国家 / 城市 / 街道 / 门牌号支持精度参数透传满足从粗粒度区域到细粒度点位的解析需求。3. POI 搜索矩阵场景化位置检索能力关键词搜索支持城市 / 区域筛选城市名称、城市编码、区域编码任选其一可搜索 “学校”“医院” 等泛化关键词或 “襄阳五中”“北京协和医院” 等精准名称返回 POI 列表包含名称、地址、坐标、类别等信息支持分页查询默认 20 条 / 页。附近搜索以指定坐标为中心格式“经度纬度”搜索半径内的 POI默认 5000 米支持按距离、评分等维度排序适用于 LBS 营销、周边服务推荐等场景搜索性能提升 40%。4. 企业级稳定性全链路质量保障兼容性支持 Chrome、Firefox、Edge 等主流浏览器兼容 iOS Safari 和 Android Chrome适配老旧设备的地理定位 API 差异。安全机制访问密钥accessKey校验机制防止未授权调用HTTPS 加密传输保障数据安全内置异常捕获机制自动处理网络错误、格式错误等问题。轻量高效无第三方依赖核心代码体积小于 100KB加载速度提升 60%支持 Tree-Shaking按需引入功能模块避免冗余代码。三、快速集成指南三步完成接入步骤 1引入 JS 文件import { loadData, getLocation, reverseGeocode, geocode, poiSearch, nearbySearch } from ./wz_location.min.js;步骤 2初始化配置// 从服务端获取有效访问密钥 const ACCESS_KEY your-access-key; loadData(ACCESS_KEY); // 初始化密钥步骤 3调用核心接口① 获取定位并解析地址含逆地理编码getLocation() .then((addressData) { // 地址数据示例{country: 中国, city: 武汉市, district: 洪山区, street: 珞喻路10号} console.log(当前位置地址, addressData); // 业务场景自动填充收货地址、显示用户所在城市 }) .catch((error) { if (error 用户拒绝了获取地理位置的请求。) { // 引导用户开启定位权限 alert(请允许获取位置信息以提供更好的服务); } else if (error.includes(超时)) { // 回退到IP定位或提示用户手动输入地址 getIPLocationFallback(); } });② 正、逆编码const address 湖北省武汉市洪山区华中科技大学; const city 武汉市; geocode(address, city) .then((coordinateData) { // 坐标数据示例{latitude: 30.5204, longitude: 114.3690, accuracy: 50} console.log(地址坐标, coordinateData); // 业务场景地图标点、路径规划起点设置 }) .catch((error) { console.error(地址解析失败, error); }); // 逆地理编码 reverseGeocode(location) .then((data) { showResult(请求成功返回数据${JSON.stringify(data)}); }) .catch((error) { showResult(请求失败${error}); });③ POI 关键词搜索查找指定城市 POI// 搜索武汉市的中学 poiSearch(中学, 武汉市) .then((searchResult) { // 结果示例{total: 200, results: [{name: 华中师范大学第一附属中学, address: 武汉市洪山区…, location: {lat: 30.5123, lng: 114.3567}}]} const poiList searchResult.results; // 业务场景教育机构地图标注、区域教育资源分析 }) .catch((error) { console.error(POI搜索失败, error); });④ 附近搜索定位点周边 POI// 假设当前定位坐标为武汉光谷广场114.4058, 30.5297 const centerLocation 114.4058,30.5297; nearbySearch(咖啡馆, , centerLocation, 1000) // 搜索1公里内的咖啡馆 .then((nearbyResults) { // 结果按距离排序最近的优先显示 nearbyResults.results.forEach((poi) { console.log(${poi.name} - 距离${poi.distance}米); }); // 业务场景商圈餐饮推荐、线下门店引流 });四、最佳实践与错误处理1. 常见问题解决方案错误类型错误信息示例解决步骤密钥无效HTTP error! status: 403① 检查 accessKey 是否正确 ② 确认密钥是否过期定位权限拒绝用户拒绝了获取地理位置的请求。① 在页面显式提示用户授权 ② 提供手动输入地址的备选方案定位超时获取地理位置信息超时。① 检查网络连接 ② 自动触发 IP 定位插件已内置 ③ 增加重试机制地址解析失败无效的地址格式① 确保地址包含省 / 市 / 区 / 街道等关键信息 ② 补充城市参数缩小范围2. 性能优化建议高频调用场景利用maximumAge: 60000参数启用 2 分钟定位缓存减少重复请求。批量搜索场景通过分页参数page_index/page_size分批获取 POI 数据避免单次请求数据量过大。隐私保护非必要场景不获取高精度定位设置enableHighAccuracy: false降低电池消耗。五、适用场景与典型案例1. 核心应用场景电商零售自动填充收货地址、附近门店查询、物流轨迹定位。本地生活餐饮娱乐推荐、服务网点导航、商圈热力分析。出行服务起点终点地址解析、周边充电桩搜索、实时位置共享。企业级应用员工考勤定位、资产追踪、智慧园区管理。2. 客户案例某连锁品牌 H5 商城痛点用户手动输入地址繁琐周边门店查询效率低。解决方案集成 JS-API 插件通过getLocation自动获取用户城市nearbySearch查询 5 公里内门店加载速度提升 40%地址相关交互转化率提升 25%。六、立即体验与支持资源1. 接入准备获取密钥登录维智开发者平台注册账号创建应用获取 accessKey。文档中心JS-API 插件文档包含接口细节、错误码列表、示例代码。插件包下载在线插件包实时查看定位搜索效果支持代码调试。2. 技术支持7×12 小时客服开发者社区留言工作日 2 小时内响应。版本更新每月发布补丁版本持续优化兼容性和性能。企业定制支持密钥权限管理、专属域名部署、定制化功能开发。
一、产品概述重新定义 H5 定位开发体验维智科技正式发布JS-API 定位插件专为 H5 页面开发者打造轻量化定位搜索解决方案。无需复杂环境配置只需引入单个 JS 文件即可快速集成定位获取、正地理编码、逆地理编码、POI 搜索四大核心能力覆盖从设备定位到场景化搜索的全流程需求。插件兼容主流浏览器支持浏览器原生定位、IP 定位等多种方式内置智能错误处理机制让开发者专注业务逻辑无需关心底层实现细节。二、核心功能优势四大能力构建全域定位生态1. 多模定位引擎精准捕获设备位置智能定位策略优先使用浏览器原生定位GPS/Wi-Fi/ 基站失败时自动回退至 IP 定位支持离线环境下的 IP 粗定位定位成功率提升 30%。快速响应内置 5 秒超时机制超时后自动触发 IP 定位避免用户长时间等待支持缓存最近 2 分钟定位结果重复请求响应速度提升 50%。隐私合规严格遵循浏览器定位权限机制支持用户授权引导符合 GDPR、《个人信息保护法》等合规要求。2. 地理编码双引擎地址与坐标双向互通正地理编码输入标准化地址如 “湖北省武汉市洪山区泛悦城”返回精准经纬度坐标支持城市限定如 “武汉市”解决同名地址歧义问题地址解析准确率达 98%。逆地理编码输入经纬度对象{latitude: 30.5234, longitude: 114.3456}返回结构化地址信息国家 / 城市 / 街道 / 门牌号支持精度参数透传满足从粗粒度区域到细粒度点位的解析需求。3. POI 搜索矩阵场景化位置检索能力关键词搜索支持城市 / 区域筛选城市名称、城市编码、区域编码任选其一可搜索 “学校”“医院” 等泛化关键词或 “襄阳五中”“北京协和医院” 等精准名称返回 POI 列表包含名称、地址、坐标、类别等信息支持分页查询默认 20 条 / 页。附近搜索以指定坐标为中心格式“经度纬度”搜索半径内的 POI默认 5000 米支持按距离、评分等维度排序适用于 LBS 营销、周边服务推荐等场景搜索性能提升 40%。4. 企业级稳定性全链路质量保障兼容性支持 Chrome、Firefox、Edge 等主流浏览器兼容 iOS Safari 和 Android Chrome适配老旧设备的地理定位 API 差异。安全机制访问密钥accessKey校验机制防止未授权调用HTTPS 加密传输保障数据安全内置异常捕获机制自动处理网络错误、格式错误等问题。轻量高效无第三方依赖核心代码体积小于 100KB加载速度提升 60%支持 Tree-Shaking按需引入功能模块避免冗余代码。三、快速集成指南三步完成接入步骤 1引入 JS 文件import { loadData, getLocation, reverseGeocode, geocode, poiSearch, nearbySearch } from ./wz_location.min.js;步骤 2初始化配置// 从服务端获取有效访问密钥 const ACCESS_KEY your-access-key; loadData(ACCESS_KEY); // 初始化密钥步骤 3调用核心接口① 获取定位并解析地址含逆地理编码getLocation() .then((addressData) { // 地址数据示例{country: 中国, city: 武汉市, district: 洪山区, street: 珞喻路10号} console.log(当前位置地址, addressData); // 业务场景自动填充收货地址、显示用户所在城市 }) .catch((error) { if (error 用户拒绝了获取地理位置的请求。) { // 引导用户开启定位权限 alert(请允许获取位置信息以提供更好的服务); } else if (error.includes(超时)) { // 回退到IP定位或提示用户手动输入地址 getIPLocationFallback(); } });② 正、逆编码const address 湖北省武汉市洪山区华中科技大学; const city 武汉市; geocode(address, city) .then((coordinateData) { // 坐标数据示例{latitude: 30.5204, longitude: 114.3690, accuracy: 50} console.log(地址坐标, coordinateData); // 业务场景地图标点、路径规划起点设置 }) .catch((error) { console.error(地址解析失败, error); }); // 逆地理编码 reverseGeocode(location) .then((data) { showResult(请求成功返回数据${JSON.stringify(data)}); }) .catch((error) { showResult(请求失败${error}); });③ POI 关键词搜索查找指定城市 POI// 搜索武汉市的中学 poiSearch(中学, 武汉市) .then((searchResult) { // 结果示例{total: 200, results: [{name: 华中师范大学第一附属中学, address: 武汉市洪山区…, location: {lat: 30.5123, lng: 114.3567}}]} const poiList searchResult.results; // 业务场景教育机构地图标注、区域教育资源分析 }) .catch((error) { console.error(POI搜索失败, error); });④ 附近搜索定位点周边 POI// 假设当前定位坐标为武汉光谷广场114.4058, 30.5297 const centerLocation 114.4058,30.5297; nearbySearch(咖啡馆, , centerLocation, 1000) // 搜索1公里内的咖啡馆 .then((nearbyResults) { // 结果按距离排序最近的优先显示 nearbyResults.results.forEach((poi) { console.log(${poi.name} - 距离${poi.distance}米); }); // 业务场景商圈餐饮推荐、线下门店引流 });四、最佳实践与错误处理1. 常见问题解决方案错误类型错误信息示例解决步骤密钥无效HTTP error! status: 403① 检查 accessKey 是否正确 ② 确认密钥是否过期定位权限拒绝用户拒绝了获取地理位置的请求。① 在页面显式提示用户授权 ② 提供手动输入地址的备选方案定位超时获取地理位置信息超时。① 检查网络连接 ② 自动触发 IP 定位插件已内置 ③ 增加重试机制地址解析失败无效的地址格式① 确保地址包含省 / 市 / 区 / 街道等关键信息 ② 补充城市参数缩小范围2. 性能优化建议高频调用场景利用maximumAge: 60000参数启用 2 分钟定位缓存减少重复请求。批量搜索场景通过分页参数page_index/page_size分批获取 POI 数据避免单次请求数据量过大。隐私保护非必要场景不获取高精度定位设置enableHighAccuracy: false降低电池消耗。五、适用场景与典型案例1. 核心应用场景电商零售自动填充收货地址、附近门店查询、物流轨迹定位。本地生活餐饮娱乐推荐、服务网点导航、商圈热力分析。出行服务起点终点地址解析、周边充电桩搜索、实时位置共享。企业级应用员工考勤定位、资产追踪、智慧园区管理。2. 客户案例某连锁品牌 H5 商城痛点用户手动输入地址繁琐周边门店查询效率低。解决方案集成 JS-API 插件通过getLocation自动获取用户城市nearbySearch查询 5 公里内门店加载速度提升 40%地址相关交互转化率提升 25%。六、立即体验与支持资源1. 接入准备获取密钥登录维智开发者平台注册账号创建应用获取 accessKey。文档中心JS-API 插件文档包含接口细节、错误码列表、示例代码。插件包下载在线插件包实时查看定位搜索效果支持代码调试。2. 技术支持7×12 小时客服开发者社区留言工作日 2 小时内响应。版本更新每月发布补丁版本持续优化兼容性和性能。企业定制支持密钥权限管理、专属域名部署、定制化功能开发。
