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 về vị trí địa lý được gửi bằng cách sử dụng 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 để quản lý hạn mức. Hãy 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 JSON. Nếu không thêm 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 đều được hỗ trợ và tất cả các trường là không bắt buộc, trừ phi có quy định khác:

Trường Loại JSON Nội dung mô tả Ghi chú
homeMobileCountryCode number (uint32) Mã di động quốc gia (MCC) cho mạng gia đình của thiết bị. Được hỗ trợ cho radioType gsm (mặc định), wcdma, ltenr; không dùng cho cdma.
Phạm vi hợp lệ: 0 – 999.
homeMobileNetworkCode number (uint32) Mã mạng di động cho mạng gia đình của thiết bị. Đây là MNC dành cho GSM, GSM, LTE và NR.
CDMA sử dụng Mã hệ thống (SID)
Phạm vi hợp lệ cho MNC: 0 – 999.
Phạm vi hợp lệ cho SID: 0–32767.
radioType string Loại radio trên thiết bị di động. Giá trị được hỗ trợ là gsmcdma, wcdma, ltenr. Mặc dù trường này là không bắt buộc, nhưng trường này phải luôn được đưa vào nếu ứng dụng đã biết loại đài.
Nếu bạn bỏ qua trường này, API vị trí địa lý sẽ đặt mặc định thành gsm. Điều này sẽ dẫn đến kết quả không hợp lệ hoặc bằng 0 nếu loại đài giả định không chính xác.
carrier string Tên nhà mạng.
considerIp boolean Chỉ định xem có quay lại chế độ định vị vị trí IP hay không nếu tín hiệu Wi-Fi và tín hiệu tháp phát sóng bị thiếu, trống hoặc không đủ để ước đoán vị trí của thiết bị. Giá trị mặc định là true. Đặt considerIp thành false để tránh tình trạng quay lại.
cellTowers array Một dãy các vật thể trong tháp phát sóng. Xem phần Đối tượng tháp ô dưới đây.
wifiAccessPoints array Một mảng các đối tượng điểm truy cập Wi-Fi. Xem phần Đối tượng điểm truy cập Wi-Fi ở bên dưới.

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.
  ]
}

Vật thể trong tháp phát sóng

Mảng cellTowers của nội dung yêu cầu không chứa hoặc có nhiều đối tượng tháp phát sóng.

Trường Loại JSON Nội dung mô tả Ghi chú
cellId number (uint32) Giá trị nhận dạng duy nhất của ô. Bắt buộc đối với radioType gsm (mặc định), cdma, wcdmalte; đã từ chối đối với nr.
Xem phần Tính toán mã nhận dạng ô bên dưới, phần này cũng liệt kê các phạm vi giá trị hợp lệ cho từng loại đài.
newRadioCellId number (uint64) Giá trị nhận dạng duy nhất của ô NR (5G). Bắt buộc đối với radioType nr; bị từ chối đối với các loại khác.
Xem phần Tính toán newRadioCellId ở bên dưới. Phần này cũng liệt kê phạm vi giá trị hợp lệ cho trường này.
locationAreaCode number (uint32) Mã vùng vị trí (LAC) cho các mạng GSM và GSM.
Mã mạng (NID) cho mạng CDMA.
Mã vùng theo dõi (TAC) cho mạng LTE và NR.
Bắt buộc đối với radioType gsm (mặc định) và cdma, không bắt buộc đối với các giá trị khác.
Phạm vi hợp lệ với gsm, cdma, wcdmalte: 0–65535.
Phạm vi hợp lệ với nr: 0–16777215.
mobileCountryCode number (uint32) Mã quốc gia di động (MCC) của trạm phát sóng. Bắt buộc đối với radioType gsm (mặc định), wcdma, ltenr; không dùng cho cdma.
Phạm vi hợp lệ: 0 – 999.
mobileNetworkCode number (uint32) Mã mạng di động của trạm phát sóng. Đây là MNC dành cho GSM, GSM, LTE và NR.
CDMA sử dụng Mã hệ thống (SID).
Bắt buộc.
Phạm vi hợp lệ cho MNC: 0–999.
Phạm vi hợp lệ cho SID: 0–32767.

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ó.

Trường Loại JSON Nội dung mô tả Ghi chú
age number (uint32) Số mili giây kể từ khi ô này là ô chính. Nếu độ tuổi là 0, thì cellId hoặc newRadioCellId sẽ biểu thị kết quả đo lường hiện tại.
signalStrength number (double) Cường độ tín hiệu vô tuyến được đo bằng dBm.
timingAdvance number (double) Giá trị thời gian nâng cao.

Đang tính 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 Mã điện thoại di động (CID) 16 bit nguyên trạng. Phạm vi hợp lệ: 0–65535.
  • Mạng CDMA (2G) sử dụng mã trạm cơ sở (BID) 16 bit. Phạm vi hợp lệ: 0 – 65535.
  • Mạng GSM (3G) sử dụng Mã nhận dạng di động UTRAN/GERAN (UC-ID). Đây là một giá trị số nguyên 28 bit nối các Giá trị nhận dạng trình điều khiển mạng vô tuyến (RNC-ID) 12 bit và Mã mạng di động (CID) 16 bit (CID).
    Công thức: rnc_id << 16 | cid.
    Phạm vi hợp lệ: 0–268435455.
    Lưu ý: Nếu chỉ định giá trị Mã nhận dạng điện thoại di động 16 bit trong mạng GMS, thì kết quả sẽ 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). Đây là một giá trị số nguyên 28 bit nối với Giá trị nhận dạng nút B E-UTRAN 20 bit (eNBId) và Mã nhận dạng di động 8 bit (CID).
    Công thức: enb_id << 8 | cid.
    Phạm vi hợp lệ: 0–268435455.
    Lưu ý: Việc 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 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. Theo quyết định của Google, API có thể cắt bớt số sao cho vừa với phạm vi được ghi nhận, dự đoán giá trị chỉnh sửa cho radioType hoặc trả về một 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ề vật thể tháp phát sóng LTE.

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

Đang tính 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ý.

  • Các mạng NR (5G) sử dụng Mã nhận dạng mạng di động mới (NCI) 36 bit như nguyên trạng.
    Phạm vi hợp lệ: 0–68719476735.

Dưới đây là ví dụ về vật thể 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 nội dung yêu cầu phải chứa hai đối tượng điểm truy cập Wi-Fi trở lên. macAddress là bắt buộc; tất cả các trường khác là không bắt buộc.

Trường Loại JSON Nội dung mô tả Ghi chú
macAddress string Địa chỉ MAC của nút Wi-Fi. Mã này thường được gọi là BSS, BSSID hoặc MAC. Bắt buộc.Chuỗi thập lục phân (:) được phân tách bằng dấu phẩy.
Chỉ có thể xác định vị trí thông qua API các địa chỉ MAC được quản lý chung. Các địa chỉ MAC khác sẽ bị tự động loại bỏ và có thể dẫn đến việc yêu cầu API bị trống. Để biết thông tin chi tiết, hãy xem phần Bỏ các điểm truy cập Wi-Fi vô ích.
signalStrength number (double) Cường độ tín hiệu hiện tại được đo bằng dBm. Đối với các điểm truy cập Wi-Fi, giá trị dBm thường là -35 hoặc thấp hơn và nằm trong khoảng từ -128 đến -10 dBm. Nhớ bao gồm cả dấu trừ.
age number (uint32) Số mili giây kể từ khi phát hiện điểm truy cập này.
channel number (uint32) Kênh mà khách hàng đang giao tiếp với điểm truy cập.
signalToNoiseRatio number (double) Tỷ lệ tín hiệu hiện tại trên tiếng ồn được đo bằng dB.

Ví dụ về đối tượng điểm truy cập Wi-Fi được minh hoạ bên dưới.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

Sau đó, bạn có thể dùng cURL để gửi yêu cầu qua 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 đó giống như sau:

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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 đang đượ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 phương thức nhập. Nếu sau khi lọc, có thể xác định được rằng lệnh gọi API vị trí địa lý không thành công, thì có thể sử dụng các giải 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 tính vị trí của ứng dụng và các yêu cầu về độ chính xác cũng như 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à với tư cách là kỹ sư ứng dụng, bạn có thể chọn áp dụng.

Các đị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ẽ tự động bị loại bỏ khỏi các yêu cầu. Bạn có thể xoá các địa chỉ MAC như vậy bằng cách đảm bảo bit thứ hai ít quan trọng thứ hai trong byte quan trọng nhất của macAddress0, ví dụ: 1 bit do 2 biểu thị 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.

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

Java
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")));
    
Python
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')]
    
JavaScript
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');
    

Việc sử dụng bộ lọc này sẽ 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 của 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ề vị trí địa lý

Yêu cầu định vị vị trí thành công sẽ trả về phản hồi ở đị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 trường con lat và một trường con lng.
  • accuracy: Độ chính xác của vị trí ước đoán, tính bằng mét. Hình này thể hiện bán kính của một hình tròn xung quanh location cho trước.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}