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

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

Yêu cầu định vị đị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 mình, đượ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 dưới dạng 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 của Geolocation API.

{
  "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 trong nội dung yêu cầu chứa từ 0 đối tượng tháp phát sóng trở lên.

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

Đang tính toán cellId

Các loại đài 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 Cell ID (CID) 16 bit như hiện tại. Phạm vi hợp lệ: 0 – 65535.
• Mạng CDMA (2G) sử dụng Mã nhận dạng trạm gốc (BID) 16 bit. Phạm vi hợp lệ: 0 – 65535.
• Mạng WCDMA (3G) sử dụng Giá trị nhận dạng ô UTRAN/GERAN (UC-ID), là một giá trị số nguyên 28 bit nối Giá trị nhận dạng bộ điều khiển mạng vô tuyến (RNC-ID) 12 bit và Giá trị 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ỉ định giá trị Cell ID 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 Mã nhận dạng ô E-UTRAN (ECI), là một giá trị số nguyên 28 bit nối Mã nhận dạng nút B E-UTRAN (eNBId) 20 bit và Mã 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ỉ định giá trị Cell ID 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ị bên ngoài các dải này trong yêu cầu API có thể dẫn đến hành vi không xác định. Theo quyết định của Google, API này có thể rút ngắn số để phù hợp với phạm vi được ghi lại, suy ra một nội dung chỉnh sửa cho radioType hoặc trả về kết quả NOT_FOUND mà không có bất kỳ chỉ báo nào trong phản hồi.

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

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

Đang tính toán newRadioCellId

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

• Mạng NR (5G) sử dụng Mã nhận dạng ô vô tuyến mới (NCI) 36 bit.
  Phạm vi hợp lệ: 0 – 68719476735.

Dưới đây là ví dụ về đối tượng trạm 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 trong phần nội dung yêu cầu phải chứa từ 2 đối tượng điểm truy cập Wi-Fi trở lên, đại diện cho các thiết bị điểm truy cập khác biệt về mặt vật lý. macAddress là bắt buộc; tất cả các trường khác đều không bắt buộc.

Dưới đây là ví dụ về một đố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 dùng thử Geolocation API với 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ể dùng cURL để đưa ra 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 nêu trên 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ó macAddresses do quản trị viên quản lý tại địa phương có thể cải thiện tỷ lệ thành công của các lệnh gọi API Geolocation 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 Geolocation API 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ũ hơn hoặc các điểm truy cập Wi-Fi có tín hiệu yếu hơn. Cách tiếp cận này là sự đánh đổi giữa nhu cầu của ứng dụng về thông tin ước đoán vị trí và độ chính xác cũng như các yêu cầu về khả năng thu hồi. 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ó thông báo. Bạn có thể xoá các địa chỉ MAC như vậy bằng cách đảm bảo rằng bit có nghĩa thứ hai của byte có nghĩa 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à một ví dụ về địa chỉ MAC mà bộ lọc này sẽ loại trừ một cách hữu ích.

Dải địa chỉ MAC từ 00:00:5E:00:00:00 đến 00:00:5E:FF:FF:FF được IANA dành riêng và thường được dùng cho các chức năng quản lý mạng và truyền tin đa hướng, điều này ngăn cả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 các địa chỉ MAC có thể sử dụng cho Dịch vụ định vị địa lý từ một mảng gồm 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, danh sách chỉ còn lại 1c:34:56:78:9a:bc. Vì danh sách này có ít hơn 2 địa chỉ MAC của Wi-Fi, nên yêu cầu sẽ không thành công và hệ thống sẽ trả về phản hồi HTTP 404(notFound).

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

Yêu cầu định vị đị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: Vĩ độ và kinh độ ước tính của người dùng, tính bằng độ. Chứa một 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 vòng tròn xung quanh location đã cho.

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