开发 Web服务 API 开发指南 高级 API 文档 智能硬件定位

智能硬件定位 最后更新时间: 2024年01月23日

产品介绍

智能硬件定位 API 使用 HTTP 协议访问远程服务的接口,支持通过服务端上传 WIFI 和基站信息来实现定位进而获取经纬度和其他位置信息。

使用 API 前您需先 申请 Key,若无高德地图 API 账号需要先申请账号。

提示

智能硬件定位接口属于高级服务接口,对于已通过企业认证的用户,我们提供每日一定量的配额以供体验(流量限制说明)。如需更多配额,可进行 商务咨询

成为开发者并创建 Key 

为了正常调用 Web 服务 API ,请先注册成为高德开放平台开发者,并申请 Web 服务的 key ,点击具体操作

适用场景

该服务仅适用于没有 Android 或 iOS 系统的智能硬件产品使用。如您的产品支持 Android 或 iOS 系统,建议使用 Android 定位 SDK 或 iOS 定位 SDK 以获得更精准效果和更丰富功能。

使用说明

第一步,申请” Web 服务 API ”密钥(Key);

第二步,拼接 HTTP 请求 URL,第一步申请的 Key 需作为必填参数一同发送;

第三步,接收 HTTP 请求返回的数据(JSON 或 XML 格式),解析数据。

如无特殊声明,接口的输入参数和输出数据编码全部统一为 UTF-8。

智能硬件定位服务目前只向企业开发者开放。

您通过企业开发者审批之后,可在 控制台-个人中心-帐号权限 页面查看调用量限制,也可在 控制台-数据分析 查询该服务的每日调用情况。

智能硬件定位

智能硬件定位 API 服务地址

URL

https://apilocate.amap.com/position?parameters

请求方式

GET

parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。下面的列表枚举了这些参数及其使用规则。

请求参数

参数名

含义

规则说明

是否必须

缺省值

key 

请求服务权限标识

用户在高德地图官网 申请 Web 服务 API 类型Key

必填 

无 

accesstype 

移动端接入网络方式 

可选值: 

移动接入网络:0 

wifi 接入网络:1 

必填 

无 

imei 

手机 imei 号 

此参数能够提高定位精度和准确度,且定位不到时可依据此参数进行跟踪排查,如没有则无法排查和跟踪问题 

必填 

无 

idfa 

ios 手机的 idfa 

此参数能够提高定位精度和准确度,且定位不到时可依据此参数进行跟踪排查,如没有则无法排查和跟踪问题 

与 imei 必填一个 

无 

smac 

手机 mac 码 

此参数能够提高定位精度和准确度,且定位不到时可依据此参数进行跟踪排查,如没有则无法排查和跟踪问题 

非必填,但建议填写 

无 

serverip 

设备接入基站时对应的网关 IP 

此参数能够提高定位精度和准确度,且定位不到时可依据此参数进行跟踪排查,如没有则无法排查和跟踪问题 

非必填,但建议填写 

无 

cdma 

是否为 cdma 

是否为 cdma:

非 cdma:0 

是 cdma:1  

accesstype=0

时,必填 

imsi 

移动用户识别码 

此参数能够提高定位精度和准确度,且定位不到时可依据此参数进行跟踪排查,如没有则无法排查和跟踪问题 

非必填,但建议填写 

无 

network 

无线网络类型 

GSM/GPRS/EDGE/HSUPA/HSDPA/WC DMA 

accesstype=0

时,必填 

 

tel 

手机号码 

 

非必填 

无 

bts 

接入基站信息 

接入基站信息,详见:表 1-2 内部参数说明 

非 CDMA 格式为:mcc/mnc/lac/cellid/signal 

CDMA 格式为:sid/nid/bid/lon/lat/signal

其中 lon/lat 可为空,格式为:sid/nid/bid/,,,/signal 

accesstype=0

时,必填 

无 

nearbts 

周边基站信息(不含接入基站信息) 

基站信息 1|基站信息 2|基站信息 3….. 

非必填 

无 

mmac 

已连热点 mac 信息 

mac/signal/ssid

如:

mac:f0:7d:68:9e:7d:18

signal:-41

ssid:TPLink 

非必填,但强烈建议填写 

无 

macs 

wifi 列表中 mac 信息 

单 mac 信息同 mmac,mac 之间使用“|” 分隔。必须填写 2 个及 2 个以上,30 个以内的方可正常定位。请不要包含移动 wifi 信息 

accesstype=1

时,必填 

无 

output 

返回数据格式类型 

可选值:JSON | XML 

可选 

JSON

  • 表 1-2 内部参数说明

参数名称 

参数含义 

是否必填 

mcc 

移动用户所属国家代码,默认值为 460 

cdma=0 时,必填 

mnc 

移动网号, 中国移动:0;中国联通:1 

cdma=0 时,必填 

lac 

位置区域码, 取值范围:0-65535 

cdma=0 时,必填 

cellid 

基站小区编号,取值范围:0-65535,0-268435455

其中 0/65535/268435455 取值不可使用

小区编号大于 65535 时为 3G 基站 

cdma=0 时,必填 

signal 

信号强度, 取值范围:0 到-113dbm. 

(如获得信号强度为正数,则请按照以下公式进行转换:获得的正信号强度 * 2 – 113) 

cdma=0 时,必填 

sid 

cdma 系统识别码 

cdma=1 时,必填 

nid 

cdma 网络识别码 

cdma=1 时,必填 

bid 

cdma 小区唯一识别码 

cdma=1 时,必填 

lon 

cdma 经度值, 手机平台接口读出的数值 

可选 

lat 

cdma 纬度值, 手机平台接口读出的数值 

可选 

mac 

mac 地址,例如:00:0f:e2:4e:aa:3e 

accesstype=1 时,必填 

ssid 

无线网络名称 

accesstype=1 时,必填 

特别说明:为了尽可能地保证您定位结果的精确性,在以上所有场景中,除了必须填写的参数外,其他可以获得的参数也请一并传入。 

例如:wifi 接入网络的情况下,也可以传入其对应的基站信息;而在移动接入网络的情况下,也可传入 wifi 列表中 mac 信息(macs)。 

返回结果参数说明

智能硬件查询的响应结果的格式由请求参数 output 指定。

名称

含义

规则说明

status

返回结果状态值

值为 0 或 1,0 表示失败;1 表示成功

info

返回状态说明

返回状态说明,status 为 0 时,info 返回错误原因,否则返回“OK”

result

定位结果列表

type

定位类型

0:没有得到定位结果;

其他数字为:正常获取定位结果

imei

手机 imei 号

location

定位经纬度

radius

定位精度半径,单位:米

desc

位置描述

country

国家

province

省份

city

城市

citycode

城市编码

adcode

区域编码

road

道路名

poi

定位附近的 poi 名称

  • info 状态表 

Info 返回值 

状态描述 

OK 

正常 

INVALID_USER_KEY 

用户 key 非法或过期 

SERVICE_NOT_EXIST 

请求服务不存在 

SERVICE_RESPONSE_ERROR 

请求服务响应错误 

INSUFFICIENT_PRIVILEGES 

无权限访问此服务 

OVER_QUOTA 

请求超出配额 

INVALID_PARAMS 

请求参数非法 

UNKNOWN_ERROR 

未知错误 

服务示例

根据接入网络方式,可以分为三种定位场景,以下对三种定位场景给出对应示例。 

  • 联网方式为 wifi 接入,即 accesstype = 1 时
https://apilocate.amap.com/position?accesstype=1&imei=352315052834187&smac=E0:DB:55:E4:C7:49&mmac=50:a7:2b:1e:56:58,-60,alibaba-inc&macs=4c:48:da:25:0b:11,-59,alibaba-inc|4c:48:da:25:1a:11,-77,alibaba-inc&serverip=10.2.166.4&output=xml&key=<用户的key>

  • 联网方式为移动接入且手机卡为非 cdma 卡,即 accesstype = 0 且 cdma = 0 时
https://apilocate.amap.com/position?accesstype=0&imei=352315052834187&smac=E0:DB:55:E4:C7:49&cdma=0&bts=460,01,40977,2205409,-65&nearbts=460,01,40977,2205409,-65|460,01,40977,2205409,-65|460,01,40977,2205409,-65&serverip=10.2.166.4&output=xml&key=<用户的key>

 

  • 联网方式为移动接入且手机卡为 cdma 卡,即 accesstype = 0 且 cdma = 1 时
https://apilocate.amap.com/position?accesstype=0&imei=352315052834187&smac=E0:DB:55:E4:C7:49&cdma=1&bts=13824,1,1838,1674723,575739,-52&serverip=10.2.166.4&output=xml&key=<用户的key>

智能硬件定位 2.0

智能硬件定位 2.0 API 服务地址

URL

https://restapi.amap.com/v5/position/IoT?parameters

请求方式

POST

parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。下面的列表枚举了这些参数及其使用规则。

​请求参数

特别说明:网络定位依赖 WiFi、基站信息作为输入。为了尽可能地保证您定位结果的精确性,在以上所有场景中,除了必须填写的参数外,其他可以获得的参数也请一并传入。 

例如:WiFi 接入网络时,也可以传入其对应的基站信息;移动接入网络时,也可以传入 WiFi 列表信息。 

参数名

含义

规则说明

是否必填

缺省值

key

请求服务权限标识

用户在高德地图官网 申请 Web 服务 API 类型 Key

diu

设备唯一编号

用于问题排查,建议填充 imei、IDFA 等唯一标识,未填则后续无法排查问题

accesstype

移动端接入网络方式

可选值:

0-未知

1-移动网络

2-wifi

cdma

手机卡是否为 CDMA 卡

可选值:非 cdma-0,cdma-1

accesstype=1时必填 

network

无线网络类型 

GSM/GPRS/EDGE/HSUPA/HSDPA/WCDMA/NR

GSM

bts

接入基站信息

非 CDMA 格式为:mcc/mnc/lac/cellid/signal/cage

CDMA 格式为:

sid/nid/bid/lon/lat/signal/cage

lon/lat 为空时,格式为:sid/nid/bid/,,,/signal/cage

基站新鲜度字段(cage)说明:单位为秒,表示信号不变持续的时间。新鲜度值越大(数据越陈旧),偏离实际位置可能越大。默认为 0。

nearbts

周边基站信息(不含接入基站) 

基站信息1|基站信息2|基站信息3….. 

historybts

历史基站信息

历史定位基站信息,用于辅助定位。格式与周边基站信息相同。

mmac

已连接 WiFi 信息

格式为:mac/signal/ssid/fresh

如:

mac:f0:7d:68:9e:7d:18

signal:-41

ssid:TPLink

fresh:0

WiFi 新鲜度字段(fresh)说明:单位为:秒,表示信号不变持续的时间。新鲜度值越大(数据越陈旧),偏离实际位置可能越大。默认为 0。

accesstype=2时必填 

macs

WiFi 列表中的 WiFi 信息

单 mac 信息同 mmac,mac 之间使用“|” 分隔。必须填写 2 个及 2 个以上,30 个以内的方可正常定位。请不要包含移动 wifi 信息 

show_fields

逆地理编码结果开关

返回参数

返回数据格式类型为 JSON

名称

类型

说明

status

String

本次 API 访问状态,如果成功返回 1,如果失败返回 0。

info

String

访问状态值的说明,如果成功返回"ok",失败返回错误原因,具体见 错误码说明

infocode

String

返回状态说明,10000 代表正确,详情参阅 info 状态表

position

Object

返回的定位结果列表

location

String

定位结果坐标,如:116.473168,39.993015

radius

int

定位精度半径,单位:米

注意以下字段如果需要返回,需要通过“show_fields”进行参数类设置。

show_fields

String

可选差异化结果返回

formatted_address

String

结构化地址信息

addressComponent

Object

地址元素列表

country

String

province

String

city

String

district

String

citycode

String

城市编码

adcode

String

区域编码

street

String

附近街道名称

road

String

周边道路名称

poi

String

周边 POI 名称

服务示例

根据接入网络方式,可以分为三种定位场景,以下对三种定位场景给出对应示例。

  • 移动网络 + cdma 卡
https://restapi.amap.com/v5/position/IoT?key=<用户的key>&accesstype=1&cdma=1&network=GSM&bts=13824,1,16689,1674783,575440,-52,0&show_fields=addressComponent
  • 移动网络 + 非 cdma 卡
https://restapi.amap.com/v5/position/IoT?accesstype=1&bts=460,00,32947,252599745,-120,-1&output=json&macs=8c:5a:c1:6a:54:e1,-59,,-1|b0:30:55:8a:02:87,-60,CMCC-2fuY,-1|20:6b:e7:a2:b2:51,-60,TP-LINK_B251,-1|18:d9:8f:0c:13:40,-60,ZS,-1|9c:6f:52:8d:0d:10,-60,CMCC-3f3c,-1&cdma=0&diu=352315052834187&key=<用户的key>&network=GSM
  • wifi 联网
https://restapi.amap.com/v5/position/IoT?mmac=E0:DB:55:E4:C7:49,0,0,0&accesstype=2&bts=460,00,32947,252599745,-120,-1&output=json&cdma=0&diu=352315052834187&key=<用户的key>&network=GSM

流量限制说明

服务

个人认证开发者 

企业开发者 

日调用超量封停

(次/日)

QPS

(次/秒)

日调用超量封停

(次/日)

QPS

(次/秒)

智能硬件定位

不开放

300000

30

智能硬件定位 2.0

不开放

300000

30

返回顶部 示例中心 常见问题 智能客服 公众号
二维码