HTTP-based location

Prerequisites

• You have created a product and a device in IoT Platform and added a custom location property (GeoLocation). For more information, see Step 1 and Step 2 in Procedure.

• The device has a token. For more information, see Obtain a token for a device.

Background information

Device location is a free value-added service from IoT Platform. It uses information such as mobile base stations, Wi-Fi APs, and IP addresses to determine a device's location. For more information, see Service overview.

HTTP request format

Devices report location data to the device location service by sending an HTTP request. Only the POST method is supported. The URL format is as follows:

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

Replace ${YourEndPoint} with the endpoint for the device region, ${ProductKey} with the ProductKey, and ${DeviceName} with the DeviceName.

The following is a sample HTTPS request:

https://iot-as-http.cn-shanghai.aliyuncs.com/topic/sys/a1GFjLP****/device123/_thing/service/post.

HTTP header format

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

HTTP body format

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

HTTP body examples

• Mobile base station location

  The following is an example of a complete HTTP body for sending mobile base station information:

  {
      "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"
  }

  The following table describes the serviceParams parameters for mobile base station location.

  Parameter	Required	Description
  type	No	The location method. Fixed at base. This parameter is optional. If you do not specify it, mobile base station location is used by default.
  imei	No	The IMEI of the mobile phone. This helps you more accurately locate and troubleshoot problems. Note If an IMEI is not available, you can use a unique device identifier instead.
  smac	No	The MAC address of the mobile phone. Improves positioning accuracy and aids in troubleshooting.
  imsi	No	International Mobile Subscriber Identity. This improves location accuracy and simplifies troubleshooting.
  cdma	Yes	Specifies whether the network is CDMA. 1: CDMA. 0: Not CDMA.
  bts	Yes	Information about the mobile base station that the device is connected to. If the network is CDMA, the bts format is: sid,nid,bid,lon,lat,signal. The lon and lat parameters can be empty. If they are empty, the format is: sid,nid,bid,,,signal. If the network is not CDMA, the bts format is: mcc,mnc,lac,cellid,signal.
  nearbts	No	Information about nearby mobile base stations, excluding the connected base station. The format is: Base Station Info 1|Base Station Info 2|Base Station Info 3.... Note Specify this parameter to improve location accuracy.

  The following table describes the bts parameters.

  Parameter	Required	Description
  mcc	Required when cdma=0.	The Mobile Country Code (MCC). This is a decimal value. The default value is 460.
  mnc	Required when cdma=0.	The Mobile Network Code (MNC). 0: China Mobile. 1: China Unicom.
  lac	Required when cdma=0.	The Location Area Code (LAC). This is a decimal value. The value must be in the range of 0 to 65535.
  cellid	Required when cdma=0.	The cell ID. This is a decimal value. The value must be in the range of 0 to 65,535 or 0 to 268,435,455. The values 0, 65,535, and 268,435,455 are invalid. If the cell ID is greater than 65,535, the mobile base station is a 3G base station.
  signal	Required when cdma=0.	The signal strength. The value must be in the range of 0 to 113 dBm. If you obtain a positive signal strength value, convert it using the following formula: (Positive Signal Strength) × 2 - 113.
  sid	Required when cdma=1.	The CDMA System Identification (SID).
  nid	Required when cdma=1.	The CDMA Network Identification (NID).
  bid	Required when cdma=1.	The unique CDMA Base Station Identification (BID).
  lon	No	The CDMA longitude value retrieved from the mobile platform API.
  lat	No	The CDMA latitude value retrieved from the mobile platform API.

• Wi-Fi AP location

  The following is an example of a complete HTTP body for sending Wi-Fi AP information:

  {
    "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"
  }

  The following table describes the serviceParams parameters for Wi-Fi AP location.

  Parameter	Required	Description
  type	Yes	The location method. Fixed at wifi.
  imei	No	The mobile phone's IMEI. Improves the accuracy of pinpointing issues and simplifies troubleshooting. Note This is required when using AMAP. If it is not available, you can use the device's unique identifier instead.
  idfa	No	The IDFA of an iOS mobile phone. Improves the accuracy of problem localization and simplifies troubleshooting.
  smac	No	The MAC address of the mobile phone. This improves location accuracy and helps with troubleshooting.
  imsi	No	International Mobile Subscriber Identity (IMSI). This helps you identify and troubleshoot problems more accurately.
  tel	No	The mobile phone number.
  mmac	No	The MAC information of the connected hot spot. Format: mac,signal,ssid. Example: f0:7d:68:9e:7d:18,-41,TPLink. Note Specify this parameter to improve location accuracy.
  macs	Yes	A list of Wi-Fi APs. Use vertical bars (|) to separate MAC addresses. You must specify 2 to 30 MAC addresses for the location to be determined correctly. Do not include mobile Wi-Fi information. Otherwise, an error is reported.

• Device IP address location

  The following are examples of a complete HTTP body for sending IPv4 and IPv6 address information.

  • Location using an IPv4 address

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

  • Location using an IPv6 address

    {
      "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"
    }

  The following table describes the serviceParams parameters for IP address location.

  Parameter	Required	Description
  type	Yes	The location method is ip.
  ip	Yes	The IP address to locate. Both IPv4 and IPv6 formats are supported.

Returned data

The following is a sample response:

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

What to do next

After the device reports its location, you can call the QueryDevicePropertyData API to query the value of the device's GeoLocation property and obtain the location information.

For more information about how to use IoT Platform cloud APIs, see Cloud-side development guide.

For more methods to obtain Thing Specification Language (TSL) model data that is reported by a device, see How to obtain TSL model data reported by a device.