Yêu cầu và phản hồi vị trí địa lý

Yêu cầu vị trí địa lý

Yêu cầu vị trí địa lý được gửi bằng phương thức POST đến URL sau:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Bạn phải chỉ định một khoá trong yêu cầu, được đưa vào dưới dạng giá trị của tham số key. key là khoá API của ứng dụng. Khoá này xác định ứng dụng của bạn cho mục đích quản lý hạn mức. Tìm hiểu cách lấy khoá.

Nội dung yêu cầu

Nội dung yêu cầu phải được định dạng là JSON. Nếu không có nội dung yêu cầu, kết quả sẽ được trả về dựa trên địa chỉ IP của vị trí yêu cầu. Các trường sau đây được hỗ trợ và tất cả các trường đều không bắt buộc, trừ phi có quy định khác:

Dưới đây là ví dụ về nội dung yêu cầu API Vị trí địa lý.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Đối tượng trạm phát sóng

Mảng cellTowers của nội dung yêu cầu chứa từ 0 đến nhiều đối tượng tháp phát sóng di động.

Các trường không bắt buộc sau đây không được sử dụng, nhưng có thể được đưa vào nếu có giá trị.

Tính toán cellId

Các loại đài phát trước NR (5G) sử dụng trường cellId 32 bit để truyền mã nhận dạng ô mạng đến API Vị trí địa lý.

• Mạng GSM (2G) sử dụng Mã nhận dạng ô (CID) 16 bit như hiện có. Phạm vi hợp lệ: 0–65535.
• Mạng CDMA (2G) sử dụng Mã trạm gốc (BID) 16 bit như hiện có. Phạm vi hợp lệ: 0–65535.
• Mạng WCDMA (3G) sử dụng mã nhận dạng ô UTRAN/GERAN (UC-ID). Đây là một giá trị số nguyên 28 bit nối liền Giá trị nhận dạng bộ điều khiển mạng vô tuyến (RNC-ID) 12 bit và Mã nhận dạng ô (CID) 16 bit.
  Công thức: rnc_id << 16 | cid.
  Phạm vi hợp lệ: 0–268435455.
  Lưu ý: Việc chỉ chỉ định giá trị Mã vùng tế bào 16 bit trong mạng WCDMA sẽ dẫn đến kết quả không chính xác hoặc bằng 0.
• Mạng LTE (4G) sử dụng Giá trị nhận dạng ô E-UTRAN (ECI), đây là một giá trị số nguyên 28 bit nối chuỗi Giá trị nhận dạng nút B E-UTRAN (eNBId) 20 bit và Giá trị nhận dạng ô (CID) 8 bit.
  Công thức: enb_id << 8 | cid.
  Phạm vi hợp lệ: 0–268435455.
  Lưu ý: Việc chỉ chỉ định giá trị Mã nhận dạng ô 8 bit trong mạng LTE sẽ dẫn đến kết quả không chính xác hoặc bằng 0.

Việc đặt các giá trị nằm ngoài các phạm vi này trong yêu cầu API có thể dẫn đến hành vi không xác định. API, theo quyết định của Google, có thể cắt bớt số để vừa với phạm vi được ghi nhận, suy ra một số sửa đổi cho radioType hoặc trả về kết quả NOT_FOUND mà không có chỉ báo nào trong phản hồi.

Dưới đây là ví dụ về đối tượng tháp phát sóng LTE.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Tính toán newRadioCellId

Các mạng mới hơn có mã ô dài hơn 32 bit sử dụng trường newRadioCellId 64 bit để truyền mã ô mạng đến API Vị trí địa lý.

• Mạng NR (5G) sử dụng mã nhận dạng ô phát sóng mới (NCI) 36 bit như hiện có.
  Dải hợp lệ: 0–68719476735.

Dưới đây là ví dụ về đối tượng tháp phát sóng NR.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

Đối tượng điểm truy cập Wi-Fi

Mảng wifiAccessPoints của phần nội dung yêu cầu phải chứa ít nhất hai đối tượng điểm truy cập Wi-Fi đại diện cho các thiết bị điểm truy cập khác nhau về mặt vật lý. macAddress là bắt buộc; tất cả các trường khác là không bắt buộc.

Dưới đây là ví dụ về đối tượng điểm truy cập Wi-Fi.

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Yêu cầu mẫu

Nếu bạn muốn thử API Vị trí địa lý bằng dữ liệu mẫu, hãy lưu JSON sau vào một tệp:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "30:86:2d:c4:29:d0",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

Sau đó, bạn có thể sử dụng cURL để tạo yêu cầu từ dòng lệnh:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

Phản hồi cho các địa chỉ MAC trước đó sẽ có dạng như sau:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Loại bỏ các điểm truy cập Wi-Fi không dùng đến

Việc xoá các đối tượng điểm truy cập Wi-Fi có macAddress được quản lý cục bộ có thể cải thiện tỷ lệ thành công của các lệnh gọi API Vị trí địa lý sử dụng Wi-Fi làm dữ liệu đầu vào. Nếu sau khi lọc, bạn có thể xác định rằng lệnh gọi API Vị trí địa lý sẽ không thành công, thì bạn có thể sử dụng các biện pháp giảm thiểu như sử dụng tín hiệu vị trí cũ hoặc AP Wi-Fi có tín hiệu yếu hơn. Phương pháp này là sự đánh đổi giữa nhu cầu của ứng dụng về thông tin ước tính vị trí và các yêu cầu về độ chính xác và khả năng gợi nhắc. Các kỹ thuật lọc sau đây minh hoạ cách lọc dữ liệu đầu vào, nhưng không cho thấy các biện pháp giảm thiểu mà bạn có thể chọn áp dụng với tư cách là kỹ sư ứng dụng.

Địa chỉ MAC được quản lý cục bộ không phải là tín hiệu vị trí hữu ích cho API và sẽ bị loại bỏ khỏi các yêu cầu mà không cần thông báo. Bạn có thể xoá các địa chỉ MAC đó bằng cách đảm bảo rằng bit có giá trị thứ hai ít quan trọng nhất của byte có giá trị quan trọng nhất của macAddress là 0, ví dụ: 1 bit được biểu thị bằng 2 trong 02:00:00:00:00:00. Địa chỉ MAC truyền tin (FF:FF:FF:FF:FF:FF) là ví dụ về địa chỉ MAC sẽ được bộ lọc này loại trừ một cách hữu ích.

Phạm vi địa chỉ MAC giữa 00:00:5E:00:00:00 và 00:00:5E:FF:FF:FF được cung cấp cho IANA và thường được dùng cho các chức năng quản lý mạng và truyền đa điểm, ngăn việc sử dụng các địa chỉ này làm tín hiệu vị trí. Bạn cũng nên xoá các địa chỉ MAC này khỏi dữ liệu đầu vào cho API.

Ví dụ: bạn có thể thu thập địa chỉ MAC có thể sử dụng cho tính năng Xác định vị trí địa lý từ một mảng các chuỗi macAddress có tên là macs:

String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16))
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16))
                           && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

Khi sử dụng bộ lọc này, chỉ còn 1c:34:56:78:9a:bc trong danh sách. Vì danh sách này có ít hơn 2 địa chỉ MAC Wi-Fi, nên yêu cầu sẽ không thành công và hệ thống sẽ trả về một phản hồi HTTP 404(notFound).

Câu trả lời về vị trí địa lý

Yêu cầu xác định vị trí địa lý thành công sẽ trả về một phản hồi có định dạng JSON xác định vị trí và bán kính.

• location: Toạ độ vĩ độ và kinh độ ước tính của người dùng, tính theo độ. Chứa một trường con lat và một trường con lng.
• accuracy: Độ chính xác của vị trí ước tính, tính bằng mét. Giá trị này biểu thị bán kính của một hình tròn xung quanh location đã cho.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}