HTTP定位

设备通过发送HTTP请求到设备定位服务来进行辅助定位,本文介绍设备如何将移动基站、WiFi AP、IP地址信息上报到设备定位服务。

前提条件

HTTP请求格式

设备通过发送HTTP请求,在设备定位服务中上报位置数据。HTTP请求只支持POST方式,URL格式为:

https://${YourEndPoint}/topic/sys/${ProductKey}/${DeviceName}/_thing/service/post

您需将${YourEndPoint}替换为设备的实际地域,${ProductKey}替换为产品名称,${DeviceName}替换为设备名称。

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

设备将数据上报到具体Topic中来实现消息通信。topic格式为:

sys/${ProductKey}/${DeviceName}/_thing/service/post

请将topic格式中的${ProductKey}${DeviceName}替换为实际内容。

Host

https接入的域名,设备的实际地域,示例:

  • 华东2(上海):iot.cn-shanghai.aliyuncs.com

  • 华南1(深圳):iot.cn-shenzhen.aliyuncs.com

  • 华北2(北京):iot.cn-beijing.aliyuncs.com

password

调用设备认证接口auth返回的token值。

Content-Type

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

body

数据格式根据定位方式有所不同。详细内容,请参见下文HTTP body示例

HTTP Body格式

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

参数

说明

id

数字,用于标识请求的ID,取值自定义。

version

版本号,固定为1.0

identifier

固定为Location.Position

serviceParams

设备发送的具体位置信息,移动基站定位、WiFi AP和设备IP地址的格式不同,详细内容,请参见下文HTTP body示例

method

固定为_thing.service.post

HTTP body示例

  • 移动基站定位

    当设备发送的是移动基站信息时,下面是一个完整的HTTP body示例:

    {
      "id": "1234",
      "version": "1.0",
      "params": {
        "identifier": "Location.Position",
        "serviceParams": {
          "imei": "35231505283****",
          "smac": "E0:DB:55:E4:**:**",
          "cdma": "0",
          "bts": "4*0,01,4****,22****9,-65",
          "nearbts": "460,01,4***7,22***09,-65|460,01,40 977,22****9,-65|460,01,40977,22****9,-65"
        }
      },
      "method": "_thing.service.post"
    }

    移动基站定位serviceParams参数说明如下:

    参数

    是否必填

    说明

    type

    定位方式,固定为base

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

    imei

    若无,可以换成设备的唯一识别码。

    手机imei号。

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

    smac

    手机mac码。

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

    imsi

    移动用户识别码。

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

    cdma

    是否为cdma。

    • 1:是cdma

    • 0:非cdma

    bts

    接入设备的移动基站信息。

    • 是cdma,bts格式如下:

      sid,nid,bid,lon,lat,signal

      其中lon和lat可以为空,当为空时格式如下:

      sid,nid,bid,,,signal

    • 非cdma,bts格式如下:

      mcc,mnc,lac,cellid,signal

    nearbts

    建议填写以提高定位精准度。

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

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

    bts参数说明如下:

    参数

    是否必填

    说明

    mcc

    当cdma=0时,必填。

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

    mnc

    当cdma=0时,必填。

    移动网号。

    • 0:中国移动

    • 1:中国联通

    lac

    当cdma=0时,必填。

    位置区域码,十进制,取值范围:0~65535。

    cellid

    当cdma=0时,必填。

    基站小区编号,十进制,取值范围:0~65535,0~268435455。

    其中 0、65535和268435455不能使用,当小区编号大于65535时,移动基站为3G基站。

    signal

    当cdma=0时,必填。

    信号强度,取值范围:0~113dbm。

    如获得信号强度为正数,请按照以下公式进行转换:

    获得的正信号强度*2–113。

    sid

    当cdma=1时,必填。

    cdma系统识别码。

    nid

    当cdma=1时,必填。

    cdma网络识别码。

    bid

    当cdma=1时,必填。

    cdma小区唯一识别码。

    lon

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

    lat

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

  • WiFi AP定位

    当设备发送的是WiFi AP信息时,下面是一个完整的HTTP body示例:

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

    WiFi AP定位serviceParams参数说明如下:

    参数

    是否必填

    说明

    type

    定位方式,固定为wifi

    imei

    使用高德地图时必填。若无,可以换成设备的唯一识别码。

    手机imei号。

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

    idfa

    使用ios系统手机的idfa。

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

    smac

    手机mac码。

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

    imsi

    移动用户识别码。

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

    tel

    手机号码。

    mmac

    建议填写该参数,用于提高定位精准度。

    已连接热点的mac信息。

    格式为:mac,signal,ssid

    示例:f0:7d:68:9e:7d:18,-41,TPLink

    macs

    WiFi AP列表。

    • 单mac信息同mmac,mac之间使用竖线(|)进行分隔。

    • 必须填写2(含)~30 个以内的mac信息,方可正常定位。

    • 不能包含移动WiFi信息,否则会报错。

  • 设备IP地址定位

    当设备发送的是IP地址信息时,下面是使用IPv4地址和IPv6地址定位时完整的HTTP Body示例。

    • 使用IPv4地址定位

      {
        "id": "123",
        "version": "1.0",
        "params": {
          "identifier": "Location.Position",
          "serviceParams": {
            "type":"ip",
            "ip": "10.1.1.1",
          },
          "method": "_thing.service.post"
        }
      }
    • 使用IPv6地址定位

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

    IP地址定位serviceParams参数说明如下:

    参数

    是否必填

    说明

    type

    定位方式为ip

    ip

    需要定位的IP地址,支持IPv4和IPv6格式。

返回数据

返回数据示例:

{
  "code": 0,
  "info": {
    "altitude": 0,
    "CoordinateSystem": 2,
    "latitude": 39.9****51,
    "longitude": 116.4***718
  },
  "message": "success"
}

参数说明如下:

参数

数据类型

说明

altitude

double

高度。

CoordinateSystem

enum

坐标类型。

  • 1:国际经纬度坐标系统。(WGS_84)

  • 2:由国测局制定,是对地理位置进行首次加密后的一种坐标系统。(GCJ_02)

latitude

double

纬度。

longitude

double

经度。

错误码说明如下:

错误码

说明

0

返回成功。

10000

未知错误。

10001

请求参数不合法。检查请求体中的如下参数:

  • identifier是否为Location.Position

  • method是否为_thing.service.post

20001

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

30002

平台内部错误。

40000

请求次数过多,流控限制。

6731

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

6732

定位参数不合法。

6733

无法定位(提供的移动基站或WiFi AP数据不在定位数据库中)。

6734

IPv6定位不支持。

6735

IP格式不正确。

6736

IP无法定位。

其他错误码

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