aMapGeoFence

singleLocation startLocation addKeywordPOIRegion addDistrictRegion addPolygonRegion removeAllGeoFence removeGeoFenceEventListener

概述

随着移动互联网飞速发展，人与手机成为了形影不离的好伙伴，围绕位置提供服务成为可能。LBS（location based service）应运而生，成为了各类APP的标配。

而定位则是实现一切LBS的基础——因为只有获取到用户的位置，才能围绕位置，为用户提供各类服务。

大家应该都有类似的经历，第一次打开一个APP，会弹出对话框，寻问是否可以使用您当前的位置。这就是我们通常说的定位功能。

定位能做什么？

1、获取用户实时位置信息，以便为其提供“附近”优质服务；

2、获取用户实时位置信息，设置地理围栏，实现信息的精准推送；

3、获得用户分布情况，通过位置大数据分析，实现高效的资源配置。

4、实时监测工作人员（专车、货运、快递、外卖等）的位置及运动轨迹，实现运力及人力的高效调度。

什么场景会用到定位？

移动互联时代，定位无处不在，任何一个应用，只要想知晓用户位置，就一定会用到定位（不管是为用户提供服务，还是用于用户分析）。 高德定位深植于各类APP中，出行、社交、O2O、P2P、旅游、新闻、天气……

1、定位可以配合地图一起使用

适用于需要定位用户当前位置，及周边人车、商户位置，并将其展示在地图上的应用，典型案例：美团、神州专车

2、定位也可以独立使用

适用于只需定位用户位置，或计算两个或多个位置间距离，无需在地图上展示的应用，典型案例：陌陌、58到家

定位的实现原理

据专家透露：同时打开手机自身的GPS定位，并开启WiFi开关（无需连接到WiFi），可以很好的提高定位精度。

小课堂：科普定位原理

为什么这样就可以提高定位精度？来，我们先来弄明白定位的原理吧！

目前，主流的手机定位方式大致分为三类：

1、GPS定位：通过手机中的GPS模块获取位置

2、基站定位：通过运营商的电信基站（2g、3g、4g等）进行定位

3、混合定位（也有叫wifi定位）：GPS+基站+wifi的混合定位方式

混合定位最为精确，高德采用的就是混合定位的方式。

我的APP如何实现定位功能呢？

定位对于APP，既然这么厉害且必须，那怎么才能在自己的APP中实现定位功能呢？

我们的 APICloud 平台已经将高德定位的 SDK 封装成了模块，开发者只需按照下述文档中所说的操作，简单几行代码即可实现负责的定位功能。

aMapGeoFence 封装了高德定位的 SDK。包括定位功能和地理围栏功能。

申请 API Key

用户在使用本模块之前需要获取高德地图API Key，Key 申请的具体流程请参照 。本模块需要的 key 可以和 aMap、 、aMapNavigation 、 模块的 key 共用。

配置 config 文件

申请到 高德地图 API Key 后，需要配置在 config.xml 文件内。配置方法如下：

  • 名称：aMapGeoFence
  • 参数：apiKey
  • 配置示例:

  • 字段描述:

    android_api_key：在高德地图开放平台申请的 android 版 ak android_api_key：在高德地图开放平台申请的 android 版 ak

    ios_api_key：在高德地图开放平台申请的 iOS 版 ak

Android配置

  2.             name="com.amap.api.v2.apikey"
  3.             value="3440f2cc7d0e5c4238641d245392eac6" />
  • 字段描述 name：固定值 value：在高德地图开放平台申请的 android 版 ak

注意：

在 iOS 平台上，若要支持后台定位需配置 config.xml 文件的 location 字段。

模块接口

configManager

配置定位信息

configManager({params}, callback(ret))

params

  • 类型：字符串
  • 描述：设定定位精度
  • 默认值：hundredMeters
  • 取值范围：
    • tenMeters：十米
    • hundredMeters：百米
    • kilometer：千米
    • threeKilometers：三千米
    • best：精确度最高

filter：

  • 类型：数字
  • 描述：位置更新所需最小距离（单位米）
  • 默认值：1.0

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true                //布尔类型；操作成功状态值
  3. }

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.configManager({
  3.     accuracy: 'hundredMeters',
  4.     filter: 1
  5. }, function(ret, err) {
  6.     if (ret.status) {
  7.         alert('定位管理器初始化成功！');
  8.     }
  9. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

singleLocation

单次地理定位，可以通过 stopUpdatingLocation 方法去取消正在进行的单次定位请求。如果当前正在连续定位，调用此方法将会失败

singleLocation({params}, callback(ret, err))

params

timeout：

  • 类型：数字
  • 描述：指定单次定位超时时间，单位为妙（s）。最小值是2s
  • 默认值：10

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true,               //布尔类型；操作成功状态值
  3.     lat:39.213,                //数字类型；定位到的纬度
  4.     accuracy: 65,              //数字类型；本次定位的精度，
  5.     altitude: 200               //数字类型；当前设备所处的海拔信息
  6.     verticalAccuracy: 10               //数字类型；垂直位置精度，无效时为负数 （仅ios支持）
  7.     course: 200               //数字类型；偏离正北方向的角度，无效时为负数，范围 0.0 - 359.9
  8.     speed: 200               //数字类型；速度，无效时为负数，单位：m/s
  9.     floor: 2               //数字类型；在建筑物的第几层，无效时不返回
  10. }

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.singleLocation({
  3.     timeout: 10
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         alert(JSON.stringify(ret));
  7.     }
  8. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

singleAddress

单次逆地理定位，可以通过 stopUpdatingLocation 方法去取消正在进行的单次定位请求。如果当前正在连续定位，调用此方法将会失败

singleAddress({params}, callback(ret))

params

timeout：

  • 类型：数字
  • 描述：指定单次定位逆地理超时时间，单位为妙（s）。最小值是2s
  • 默认值：5

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true,               //布尔类型；操作成功状态值
  3.     address: {
  4.        formattedAddress: '',   //字符串类型；格式化地址
  5.        country: '',            //字符串类型；国家
  6.        province: '',           //字符串类型；省/直辖市
  7.        city: '',               //字符串类型；市
  8.        district: '',           //字符串类型；区
  9.        township: '',           //字符串类型；乡镇(android不支持)，已废弃，建议用aMap模块的getNameFromCoords接口获取
  10.        neighborhood: '',       //字符串类型；社区(android不支持)，已废弃，建议用aMap模块的getNameFromCoords接口获取
  11.        building: '',           //字符串类型；建筑(android不支持)，已废弃，建议用aMap模块的getNameFromCoords接口获取
  12.        citycode: '',           //字符串类型；城市编码
  13.        adcode: '',             //字符串类型；区域编码
  14.        street: '',             //字符串类型；街道名称
  15.        number: '',             //字符串类型；门牌号
  16.        POIName: '',            //字符串类型；兴趣点名称
  17.        AOIName: ''             //字符串类型；所属兴趣点名称
  19. }

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.singleAddress({
  3.     timeout: 10
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         alert(JSON.stringify(ret));
  7.     }
  8. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

startLocation

开始连续定位，可以通过 stopUpdatingLocation 方法去取消。调用此方法会cancel掉所有的单次定位请求

startLocation(callback(ret))

ret：

  • 类型：JSON 对象
  • 内部字段：

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.startLocation(function(ret, err) {
  3.     if (ret.status) {
  4.         alert(JSON.stringify(ret));
  5.     }
  6. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopUpdatingLocation

停止连续定位，调用此方法会cancel掉所有的单次定位请求，可以用来取消单次定位

stopUpdatingLocation()

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.stopUpdatingLocation();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addKeywordPOIRegion

根据关键字创建POI围栏

addKeywordPOIRegion({params})

params

keyword：

  • 类型：字符串
  • 描述：要查询的关键字，多个关键字用“|”分割
  • 默认值：无

type：

  • 类型：字符串
  • 描述：要查询的POI类型，多个类型用“|”分割。
  • 默认值：无

customID：

  • 类型：字符串
  • 描述：用户自定义ID
  • 默认值：无

city：

  • 类型：字符串
  • 描述：（可选项）要查询的城市
  • 默认值：无

size：

  • 类型：数字
  • 描述：（可选项）要查询的数据的条数，(0,25]，传入<=0的值为10，传入大于25的值为25，默认10
  • 默认值：10

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.addKeywordPOIRegion({
  3.                                keyword: '北京大学',
  4.                                type: '高等院校',
  5.                                customID: '111',
  6.                                city: '北京',
  7.                                size: 20,
  8.                                });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addAroundPOIRegion

根据经纬度进行周边搜索创建POI围栏

addAroundPOIRegion({params})

params

location：

  • 类型：JSON 对象
  • 描述：点的经纬度坐标，必填
  • 内部字段：
  1. {
  2.     latitude: 0,   // 数字类型；纬度；默认值：无
  3.     longitude: 0,   // 数字类型；经度；默认值：无
  4.   }

customID：

  • 类型：字符串
  • 描述：用户自定义ID
  • 默认值：无

keyword：

  • 类型：字符串
  • 描述：（可选项）要查询的关键字，多个关键字用“|”分割
  • 默认值：无

type：

  • 类型：字符串
  • 描述：（可选项）要查询的POI类型，多个类型用“|”分割
  • 默认值：无
  • 类型：数字
  • 描述：（可选项）查询半径，单位：米，(0,50000]，超出范围取3000，默认3000
  • 默认值：3000

size：

  • 类型：数字
  • 默认值：10

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.addAroundPOIRegion({
  3.                         location:{
  4.                             latitude:39.908692,
  5.                             longitude:116.397477
  6.                         },
  7.                         keyword: '肯德基',
  8.                         type: '050301',
  9.                         customID: '222',
  10.                         aroundRadius: 10000,
  11.                         size: 20,
  12.                     });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addDistrictRegion

创建行政区域围栏

addDistrictRegion({params})

params

districtName：

  • 类型：字符串
  • 描述：行政区域关键字，必填，只支持单个关键词语：行政区名称、citycode、adcode。规则
  • 默认值：无

customID：

  • 类型：字符串
  • 描述：用户自定义ID
  • 默认值：无

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.addDistrictRegion({
  3.                                districtName: '海淀区',
  4.                                customID: '333'
  5.                                });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addCircleRegion

创建自定义圆形围栏

addCircleRegion({params})

center：

  • 类型：JSON 对象
  • 描述：围栏的中心点经纬度坐标
  • 内部字段：
  1. {
  2.     latitude: 0,   // 数字类型；纬度；默认值：无
  3.     longitude: 0,   // 数字类型；经度；默认值：无
  4.   }

customID：

  • 类型：字符串
  • 描述：用户自定义ID
  • 默认值：无

radius：

  • 类型：数字
  • 描述：（可选项）围栏的半径，单位：米，要求大于0
  • 默认值：3000

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addPolygonRegion

创建自定义多边形围栏

addPolygonRegion({params})

params

coordinates：

  • 类型：数组
  • 描述：经纬度坐标点数据，经纬度坐标点的个数不可小于3个
  • 内部字段：
  2.      {
  3.         latitude: 0,   // 数字类型；纬度；默认值：无
  4.         longitude: 0,   // 数字类型；经度；默认值：无
  5.       }
  6.   ]

customID：

  • 类型：字符串
  • 描述：用户自定义ID
  • 默认值：无

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.addPolygonRegion({
  3.                    coordinates:[
  4.                         {
  5.                             latitude:39.933921,
  6.                             longitude:116.372927
  7.                         },
  8.                         {
  9.                             latitude:39.907261,
  10.                             longitude:116.376532
  11.                         },
  12.                         {
  13.                             latitude:39.900611,
  14.                             longitude:116.418161
  15.                         },
  16.                         {
  17.                             latitude:39.941949,
  18.                             longitude:116.435497
  19.                         }
  20.                    ],
  21.                    customID: '555'
  22.                                });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removeGeoFence

根据customID移除围栏

removeGeoFence({params})

params

customID：

  • 类型：字符串
  • 描述：用户自定义ID
  • 默认值：无

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.removeGeoFence({
  3.                                customID: '555'
  4.                             });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removeAllGeoFence

移除所有围栏

removeAllGeoFence()

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.removeAllGeoFence();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addGeoFenceEventListener

添加监听

addGeoFenceEventListener(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     customID:'111',      //字符串类型；用户添加围栏的传入的自定义ID
  3.     fenceId:'',                //字符串类型；围栏Id（仅Android支持）
  4.     status:      //字符串类型；围栏的状态
  5.     //取值范围：
  6.      //'add' : 添加围栏（仅ios支持）
  7.       //'inside' : 进入围栏
  8.       //'outside' : 退出围栏
  9.       //'stayed' : 在围栏内停留
  10.        //'unknown' : 未知
  11. }

示例代码

  1. var aMapGeoFence = api.require('aMapGeoFence');
  2. aMapGeoFence.addGeoFenceEventListener(function(ret) {
  3.           if (ret) {
  4.               alert(JSON.stringify(ret));
  5.           }
  6.       });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removeGeoFenceEventListener

移除监听

removeGeoFenceEventListener()

  2. aMapGeoFence.removeGeoFenceEventListener();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本