文档

HTTP定位

更新时间:

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

前提条件

  • 已在物联网平台创建产品和设备,并添加自定义设备的位置属性(GeoLocation)。具体操作,请参见使用流程的步骤1和步骤2。

  • 设备已获取Token。 具体操作,请参见获取设备的Token

背景信息

设备定位是物联网平台提供的免费增值服务,可根据设备提供的移动基站、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}

参数

说明

POST

${topic}替换为具体Topic,设备将数据上报到具体Topic中来实现消息通信。

Topic格式为:sys/${ProductKey}/${DeviceName}/_thing/service/post

请将Topic格式中的${ProductKey}${DeviceName}替换为实际设备信息。

Host

${YourEndpoint}替换为HTTPS接入的域名,设备实际地域的接入域名,请参见查看实例终端节点

password

${token}替换为调用设备认证接口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

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

method

固定为_thing.service.post

HTTP Body示例

  • 移动基站定位

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

    {
        "id":"1234",
        "version":"1.0",
        "params":{
            "identifier":"Location.Position",
            "serviceParams":{
                "type":"base",
                "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号。

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

    说明

    若无手机IMEI号,可换成设备的唯一识别码。

    smac

    手机MAC码。

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

    imsi

    移动用户识别码。

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

    cdma

    是否为CDMA。

    • 1:是CDMA。

    • 0:非CDMA。

    bts

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

    • 是CDMA,bts格式:sid,nid,bid,lon,lat,signal

      其中lonlat可以为空,当为空时格式: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

    Wi-Fi AP列表。

    • MAC之间使用竖线(|)进行分隔。

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

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

  • 设备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

请求参数异常。检查请求体中的如下参数(包括但不限于):

  • Topic格式是否为:sys/${ProductKey}/${DeviceName}/_thing/service/post

  • identifier是否为Location.Position

  • method是否为_thing.service.post

20001

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

30002

平台内部错误。

40000

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

6731

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

6732

定位参数不合法。

6733

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

6734

IPv6定位不支持。

6735

IP格式不正确。

6736

IP无法定位。

其他错误码

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

后续操作

设备上报位置信息后,您可调用QueryDevicePropertyData接口查询设备的属性GeoLocation)值,获取设备的位置信息。

物联网平台云端API使用方法,请参见云端开发指南

更多获取设备上报物模型数据的方法,请参见如何获取设备上报的物模型数据

  • 本页导读 (1)
文档反馈