aMapGeoFence

来自于:开发者立即使用

概述

随着移动互联网飞速发展,人与手机成为了形影不离的好伙伴,围绕位置提供服务成为可能。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。本模块需要的 key 可以和 aMapaMapLocationaMapNavigationaMapReportLocation 模块的 key 共用。

配置 config 文件

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

  • 名称:aMapGeoFence
  • 参数:apiKey
  • 配置示例:
  <feature name="aMapGeoFence">
    <param name="android_api_key" value="3440f2cc7d0e5c4238641d245392eac6" />
    <param name="ios_api_key" value="dd5343be258aa304698e42cd0fc761cd" />
  </feature>
  • 字段描述:

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

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

Android配置

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

注意:

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

模块接口

configManager

配置定位信息

configManager({params}, callback(ret))

params

accuracy:

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

filter:

  • 类型:数字
  • 描述:位置更新所需最小距离(单位米)
  • 默认值:1.0

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status:true                //布尔类型;操作成功状态值
}

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.configManager({
    accuracy: 'hundredMeters',
    filter: 1
}, function(ret, err) {
    if (ret.status) {
        alert('定位管理器初始化成功!');
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

singleLocation

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

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

params

timeout:

  • 类型:数字
  • 描述:指定单次定位超时时间,单位为妙(s)。最小值是2s
  • 默认值:10

callback(ret)

ret:

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

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.singleLocation({
    timeout: 10
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

singleAddress

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

singleAddress({params}, callback(ret))

params

timeout:

  • 类型:数字
  • 描述:指定单次定位逆地理超时时间,单位为妙(s)。最小值是2s
  • 默认值:5

callback(ret)

ret:

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

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.singleAddress({
    timeout: 10
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startLocation

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

startLocation(callback(ret))

callback(ret)

ret:

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

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.startLocation(function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopUpdatingLocation

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

stopUpdatingLocation()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addKeywordPOIRegion

根据关键字创建POI围栏

addKeywordPOIRegion({params})

params

keyword:

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

type:

customID:

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

city:

  • 类型:字符串
  • 描述:(可选项)要查询的城市
  • 默认值:无

size:

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

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addKeywordPOIRegion({
                               keyword: '北京大学',
                               type: '高等院校',
                               customID: '111',
                               city: '北京',
                               size: 20,
                               });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addAroundPOIRegion

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

addAroundPOIRegion({params})

params

location:

  • 类型:JSON 对象
  • 描述:点的经纬度坐标,必填
  • 内部字段:
{
    latitude: 0,   // 数字类型;纬度;默认值:无
    longitude: 0,   // 数字类型;经度;默认值:无
  }

customID:

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

keyword:

  • 类型:字符串
  • 描述:(可选项)要查询的关键字,多个关键字用“|”分割
  • 默认值:无

type:

  • 类型:字符串
  • 描述:(可选项)要查询的POI类型,多个类型用“|”分割
  • 默认值:无

aroundRadius:

  • 类型:数字
  • 描述:(可选项)查询半径,单位:米,(0,50000],超出范围取3000,默认3000
  • 默认值:3000

size:

  • 类型:数字
  • 描述:要查询的数据的条数,(0,25],传入<=0的值为10,传入大于25的值为25,默认10
  • 默认值:10

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addAroundPOIRegion({
                        location:{
                            latitude:39.908692,
                            longitude:116.397477
                        },
                        keyword: '肯德基',
                        type: '050301',
                        customID: '222',
                        aroundRadius: 10000,
                        size: 20,
                    });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addDistrictRegion

创建行政区域围栏

addDistrictRegion({params})

params

districtName:

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

customID:

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

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addCircleRegion

创建自定义圆形围栏

addCircleRegion({params})

params

center:

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

customID:

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

radius:

  • 类型:数字
  • 描述:(可选项)围栏的半径,单位:米,要求大于0
  • 默认值:3000

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addCircleRegion({
                         center:{
                             latitude:39.908692,
                             longitude:116.397477
                         },
                         radius: 300,
                         customID: '444'
                   });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addPolygonRegion

创建自定义多边形围栏

addPolygonRegion({params})

params

coordinates:

  • 类型:数组
  • 描述:经纬度坐标点数据,经纬度坐标点的个数不可小于3个
  • 内部字段:
[
     {
        latitude: 0,   // 数字类型;纬度;默认值:无
        longitude: 0,   // 数字类型;经度;默认值:无
      }
  ]

customID:

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

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addPolygonRegion({
                   coordinates:[
                        {
                            latitude:39.933921,
                            longitude:116.372927
                        },
                        {
                            latitude:39.907261,
                            longitude:116.376532
                        },
                        {
                            latitude:39.900611,
                            longitude:116.418161
                        },
                        {
                            latitude:39.941949,
                            longitude:116.435497
                        }
                   ],
                   customID: '555'
                               });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

removeGeoFence

根据customID移除围栏

removeGeoFence({params})

params

customID:

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

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

removeAllGeoFence

移除所有围栏

removeAllGeoFence()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addGeoFenceEventListener

添加监听

addGeoFenceEventListener(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    customID:'111',      //字符串类型;用户添加围栏的传入的自定义ID
    fenceId:'',                //字符串类型;围栏Id(仅Android支持)
    status:      //字符串类型;围栏的状态
    //取值范围:
     //'add' : 添加围栏(仅ios支持)
      //'inside' : 进入围栏
      //'outside' : 退出围栏
      //'stayed' : 在围栏内停留
       //'unknown' : 未知
}

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addGeoFenceEventListener(function(ret) {
          if (ret) {
              alert(JSON.stringify(ret));
          }
      });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

removeGeoFenceEventListener

移除监听

removeGeoFenceEventListener()

示例代码

var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.removeGeoFenceEventListener();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本