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 mình, được đưa vào dưới dạng giá trị của a key tham số. A 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:

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

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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 0 hoặc nhiều đối tượng trạm phát só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ị có sẵn.

Tính toán cellId

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

• Mạng GSM (2G) sử dụng Mã ô (CID) 16 bit như hiện tại. 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 tại. Phạm vi hợp lệ: 0–65535.
• Mạng WCDMA (3G) sử dụng Mã nhận dạng ô UTRAN/GERAN (UC-ID), là một giá trị số nguyên 28 bit nối Mã nhận dạng bộ điều khiển mạng vô tuyến (RNC-ID) 12 bit và Mã ô (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ã ô 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ã ô (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ã ô 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ố để phù hợp với phạm vi được ghi lại, suy ra một bản sửa lỗ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 trạm phát sóng LTE, là một phần của nội dung yêu cầu.

{
  ...

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

Phản hồi cho yêu cầu trước đó có dạng như sau:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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 64 bit newRadioCellId để truyền mã ô 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 như hiện tại.
  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, là một phần của nội dung yêu cầu.

{
  ...

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

Phản hồi cho yêu cầu trước đó có dạng như sau:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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

Mảng wifiAccessPoints của nội dung yêu cầu phải chứa hai hoặc nhiều đối tượng điểm truy cập Wi-Fi đại diện cho các thiết bị điểm truy cập cố định về mặt vật lý. Trường macAddress là bắt buộc. Tất cả các trường khác đều không bắt buộc. Dịch vụ này bỏ qua các điểm truy cập di chuyển, chẳng hạn như các điểm truy cập trên máy bay và tàu hoả.

Ví dụ về đối tượng điểm truy cập Wi-Fi, là một phần của nội dung yêu cầu, được trình bày bên dưới.

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

Phản hồi cho yêu cầu trước đó có dạng như sau:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Yêu cầu mẫu

Nếu bạn muốn dùng thử API Vị trí địa lý 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ể sử 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 trước đó 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 là địa chỉ truyền tin (FF:FF:FF:FF:FF:FF) hoặc do IANA dành riêng có thể cải thiện tỷ lệ thành công của các lệnh gọi API Định vị vị trí sử dụng Wi-Fi làm thông tin đầ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ũ hơn hoặc các điểm truy cập 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ề ước tính vị trí và các yêu cầu về độ chính xác 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, với tư cách là kỹ sư ứng dụng, có thể chọn áp dụng.

Phạm vi địa chỉ MAC từ 00:00:5E:00:00:00 và 00:00:5E:FF:FF:FF được dành riêng cho IANA và thường được dùng cho các chức năng quản lý mạng và phát đa hướng, ngăn không cho 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 Vị trí địa lý từ một mảng các chuỗi macAddress có tên là macs:

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

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

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

Việc sử dụng bộ lọc này sẽ chỉ còn lại 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à phản hồi HTTP 404 (notFound) sẽ được trả về.

Phản hồi vị trí địa lý

Yêu cầu định vị vị trí thành công sẽ trả về 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 bằng độ. Chứa một lat và một lng trường con.
• accuracy: Độ chính xác của vị trí ước đoán, 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
}

API trả về vị trí và bán kính độ chính xác dựa trên các tín hiệu đầu vào. Mặc dù API có thể trả về vị trí có độ chính xác cao, nhưng độ chính xác có thể thay đổi tuỳ thuộc vào nguồn, số lượng, mật độ và cường độ của các tín hiệu có sẵn. Thông thường, bạn có thể mong đợi các bán kính độ chính xác sau:

• Điểm truy cập Wi-Fi: Nếu yêu cầu bao gồm 2 hoặc nhiều wifiAccessPoints, thì bán kính độ chính xác được trả về thường là khoảng 20 mét. Độ chính xác sẽ cải thiện theo số lượng điểm truy cập và tín hiệu mạnh hơn (được đo bằng dBm), với cường độ tín hiệu thường nằm trong khoảng từ -100 đến -20 dBm.
• Trạm phát sóng: Nếu thông tin Wi-Fi không có sẵn hoặc không đủ, API sẽ sử dụng cellTowers cho vị trí. Độ chính xác thay đổi đáng kể theo loại trạm phát sóng, cường độ tín hiệu và mật độ mạng:
  • Ô vĩ mô (loại phổ biến nhất, dùng để phủ sóng diện rộng ) cung cấp độ chính xác thấp hơn. Bán kính thường nằm trong khoảng hàng trăm mét và có thể lên đến vài nghìn mét ở những khu vực có phạm vi phủ sóng trạm phát sóng thưa thớt. Đối với các ô vĩ mô, bạn hiếm khi đạt được bán kính độ chính xác dưới 100 mét. Độ chính xác thường cao hơn đối với các trạm phát sóng có tín hiệu mạnh. Tín hiệu mạnh thường là > -110 dBm đối với LTE (phạm vi tín hiệu từ -140 đến -55 dBm), > -100 dBm đối với WCDMA (phạm vi tín hiệu từ -111 đến -53 dBm), > -100 dBm đối với CDMA (phạm vi tín hiệu từ -120 đến -40 dBm) và > -80 dBm đối với GSM (phạm vi tín hiệu từ -121 đến -1 dBm).
  • Ô nhỏ (ví dụ: femtocell, picocell hoặc bộ lặp trong nhà) cung cấp vị trí chính xác nhất dựa trên ô, với bán kính độ chính xác có thể nằm trong phạm vi từ 10 đến 30 mét.
• Vị trí địa lý IP: Nếu considerIp là true và không thể xác định vị trí địa lý của tín hiệu Wi-Fi hoặc trạm phát sóng, thì API sẽ ước tính vị trí dựa trên địa chỉ IP của yêu cầu. Phương pháp này cung cấp độ chính xác thấp nhất, với bán kính có thể lên đến hàng nghìn mét. Xem bài viết Tại sao bán kính độ chính xác lại rất lớn? trong hướng dẫn Khắc phục sự cố.