全部产品

HTTP定位

本文介绍设备如何上报移动基站、WiFi AP、或者设备的IP地址到阿里云物联网平台来获取设备经纬度数据。

设备通过发送HTTP请求到设备定位服务来获取设备的经纬度,发送请求前需要接入阿里云物联网平台获取到设备的认证token。

认证token获取

参照HTTPS接入将设备接入阿里云物联网平台并获取到认证token。

HTTP请求格式说明

HTTP请求只支持通过POST方式发起请求,URL格式为:https://${YourEndPoint}/topic/sys/${ProductKey}/${DeviceName}/_thing/service/post

例如:假设当前设备名称为device123,产品的ProductKey为a1GFjLP****,并且产品位于华东2(上海)的公共实例,那么完整的HTTPS请求为: https://iot-as-http.cn-shanghai.aliyuncs.com/topic/sys/a1GFjLP****/device123/_thing/service/post

HTTP Header中的上报请求格式与参数包括:

POST /topic/${topic} HTTP/1.1
Host: ${YourEndpoint}
password:${token}
Content-Type: application/octet-stream
body: ${your_data}

参数说明:

参数

说明

topic

格式为/sys/{productKey}/{deviceName}/_thing/service/post

Host

Endpoint地址。

password

放在Header中的参数,取值为调用设备认证接口auth返回的token值。

Content-Type

设备发送给物联网平台的上行数据的编码格式,目前仅支持application/octet-stream。若使用其他编码格式,会返回参数错误。

body

数据格式根据不同的定位方式有所不同,下面会进行详细描述

HTTP Body格式

Body的格式如下:

{
  "id": "xxx",
  "version": "1.0",
  "params": {
    "identifier": "Location.Position",
    "serviceParams": {params}
  },
  "method": "_thing.service.post"
}

下面对Body参数的取值进行说明:

Body参数

描述

id

数字,用于标识请求的ID,取值由调用者设置

version

固定为"1.0"

identifier

固定为"Location.Position"

serviceParams

内容根据移动基站、WiFi AP、设备IP地址而不一样

method

固定为"_thing.service.post"

serviceParams格式说明

  • 移动基站辅助定位

移动基站定位serviceParams参数:

标识符

含义

数据类型

规则说明

是否必填

描述

type

定位类型

text

定位方式,固定为base

可不填,默认为移动基站定位

imei

手机imei号

text(字符串)

提高定位精度和排查问题。

如没有可换成设备唯一识别码。

smac

手机mac码

text(字符串)

提高定位精度和排查问题。

imsi

移动用户识别码

text(字符串)

提高定位精度和排查问题。

cdma

是否为cdma

text(字符串)

是否为cdma。非cdma:0cdma:1

bts

接入设备的基站的信息

text(字符串)

接入基站信息, 内部参数说明如下:非cdma:格式为mcc,mnc,lac,cellid,signal。

cdma:格式为sid,nid,bid,lon,lat,signal其中 lon和lat可为空,则格式为sid,nid,bid,,,signal。

nearbts

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

text(字符串)

格式如下:基站信息 1|基站信息 2|基站信息 3.....

建议填写以提高

bts参数说明:

参数名称

参数含义

是否必填

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 纬度值, 手机平台接口读出的数值

可选

下面是一个完整的发送移动基站信息的HTTP body数据示例:

{
  "id": "1234",
  "version": "1.0",
  "params": {
    "identifier": "Location.Position",
    "serviceParams": {
      "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,40 977,2205409,-65|460,01,40977,2205409,-65"
    }
  },
  "method": "_thing.service.post"
}

  • WiFi AP辅助定位

WiFi AP定位serviceParams参数:

标识符

含义

数据类型

规则说明

是否必填

描述

type

定位类型

text

定位方式,固定为wifi

imei

手机 imei 号

text(字符串)

提高定位精度和排查问题。

若没有可换的设备唯一识别码,可不填写。使用高德地图时要求必填。

idfa

ios 手机的 idfa

text(字符串)

提高定位精度和排查问题。

smac

手机 mac 码

text(字符串)

提高定位精度和排查问题。

imsi

移动用户识别码

text(字符串)

提高定位精度和排查问题。

tel

手机号码

text(字符串)

mmac

已连热点mac信息

text(字符串)

格式为mac,signal,ssid,如:f0:7d:68:9e:7d:18,-41,TPLink。

建议传入该参数,否则影响定位精度。

macs

WiFi AP列表

text(字符串)

单mac信息同mmac,mac之间使用竖线(|)进行分隔。必须填写2(含)~30 个以内mac信息方可正常定位。请不要包含移动WiFi信息。

下面是一个WiFi定位时HTTP Body的示意:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "identifier": "Location.Position",
    "serviceParams": {
      "type": "wifi",
      "mmac": "4c:48:da:26:ea:d9,-56,alibaba-inc",
      "macs": "4c:48:da:26:ea:d8,-56,alibaba-guest|e6:a4:71:6e:45:83,-58,DIRECT-RIDESKTOP-P0FPLV4mshO"
    },
    "method": "_thing.service.post"
  }
}

  • 设备IP地址辅助定位

IP地址定位serviceParams参数:

识符

含义

数据类型

规则说明

是否必填

描述

type

定位类型

text

定位方式,值固定为ip

ip

ip地址

text(字符串)

需要定位的ip,支持ipv4格式和ipv6格式

下面是使用IPv4地址定位时HTTP Body的示例:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "identifier": "Location.Position",
    "serviceParams": {
      "type":"ip",
      "ip": "11.32.423.21",
    },
    "method": "_thing.service.post"
  }
}

下面是使用IPv6地址定位时HTTP Body的示例:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "identifier": "Location.Position",
    "serviceParams": {
      "type":"ip",
      "ip": "2001:da8:5015:50:21e3:d3f5:85c5:1cbe",
    },
    "method": "_thing.service.post"
  }
}

返回数据

物联网平台对HTTPS Post返回的数据格式示例如下:

{
  "code": 0,
  "info": {
    "altitude": 0,
    "CoordinateSystem": 2,
    "latitude": 39.9932251,
    "longitude": 116.4727718
  },
  "message": "success"
}

返回参数表:

JSON对象参数标识符

参数数据类型

参数解释

longitude

double

经度。

latitude

double

纬度。

altitude

double

高度。

CoordinateSystem

enum1:WGS_842:GCJ_02

为了描述或确定位置,必须建立坐标系统,坐标只有存在于某个坐标系统才有实际的意义与具体的位置。以下是两种不同类型的坐标类型:WGS_84:国际经纬度坐标标准。GCJ_02:由国测局制定,是对地理位置进行首次加密后的一种坐标类型。

code说明

错误码

错误原因

0

成功返回

10000

未知错误

10001

请求参数不合法,请检查数据上报的identifier是否为"Location.Position",method是否为"_thing.service.post"

20001

无效token,认证失败,请检查token

30002

平台内部错误

40000

请求次数过多,流控限制

6731

定位失败(网络异常、系统异常、服务不可访问等)

6732

定位参数不合法

6733

无法定位(提供基站或wifi数据不在定位数据库中)

6734

ipv6定位不支持

6735

ip格式不正确

6736

ip无法定位

其他错误码

查询HTTP连接通信中的错误码定义。