前提條件

• 已在物聯網平臺創建產品和設備，并添加自定義設備的位置屬性（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}

HTTP Body格式

{
  "id": "xxx",
  "version": "1.0",
  "params": {
    "identifier": "Location.Position",
    "serviceParams": {params}
  },
  "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。 其中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	是	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"
}

后續操作

設備上報位置信息后，您可調用QueryDevicePropertyData接口查詢設備的屬性（GeoLocation）值，獲取設備的位置信息。

物聯網平臺云端API使用方法，請參見云端開發指南。

更多獲取設備上報物模型數據的方法，請參見如何獲取設備上報的物模型數據。