Trang này được dịch bởi Cloud Translation API.

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

Yêu cầu định vị vị trí

Yêu cầu định vị vị trí được gửi bằng cách POST tới 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, khoá này đượ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. 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 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. Sau đây là các trường đượ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:

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`, `lte` và `nr`; không được 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 ID 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 đài di động. Các giá trị được hỗ trợ: `gsm`, `cdma`, `wcdma`, `lte` và `nr`.	Mặc dù 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 phát thanh. Nếu bạn bỏ qua trường này, thì 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 được giả định là không chính xác.
`carrier`	`string`	Tên nhà mạng.
`considerIp`	`boolean`	Chỉ định xem có quay lại vị trí định vị IP hay không nếu tín hiệu Wi-Fi và trạm phát sóng bị thiếu, trống hoặc không đủ để ước tính 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 đối tượng 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.	Hãy 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 dụng trong trạm 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`, `wcdma` và `lte`; bị từ chối đối với `nr`. Hãy xem phần Tính toán mã nhận dạng ô (cellId) bên dưới để biết danh sách các dải giá trị hợp lệ cho từng loại đài phát.
`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. Hãy 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ã khu vực vị trí (LAC) cho mạng GSM và GSM. Mã mạng (NID) cho các mạng CDMA. Mã khu vực theo dõi (TAC) cho các 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`, `wcdma` và `lte`: 0–65535. Phạm vi hợp lệ với `nr`: 0–16777215.
`mobileCountryCode`	`number` (`uint32`)	Mã di động (MCC) của trạm phát sóng.	Bắt buộc đối với `radioType` `gsm` (mặc định), `wcdma`, `lte` và `nr`; không được 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 ID 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ác giá trị có sẵn.

Trường	Loại JSON	Nội dung mô tả	Ghi chú
`age`	`number` (`uint32`)	Số mili giây kể từ ô này là ô chính.	Nếu độ tuổi là 0, thì `cellId` hoặc `newRadioCellId` sẽ đại diện cho 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 ứng trước.

Đang tính `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ã nhận dạng ô của mạng đến API vị trí địa lý.

Mạng GSM (2G) sử dụng mã (CID) 16 bit. Phạm vi hợp lệ: 0 – 65535.
Mạng CDMA (2G) sử dụng Mã trạm cơ sở (BID) 16 bit như hiện tại. 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 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 điện thoại di độ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ị Mã nhận dạng di động 16 bit trong mạng GSM 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 mạng di động E-UTRAN (ECI). Đây là giá trị số nguyên 28 bit nối với Giá trị nhận dạng nút B 20 bit E-UTRAN (eNBId) và Mã mạ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ị 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 giá trị bên ngoài những 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 riêng Google, API có thể cắt bớt số để nằm trong phạm vi được ghi lại, suy ra biện pháp 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ề đố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
    }
  ]
}

Đang tính `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ã nhận dạng ô mạng sang API vị trí địa lý.

Các mạng NR (5G) sử dụng đúng Giá trị nhận dạng mạng di động mới (NCI) 36 bit mới.
Phạm vi 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 nội dung yêu cầu phải chứa 2 đố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. Địa chỉ này thường được gọi là địa chỉ 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ó các địa chỉ MAC được quản lý chung mới có thể được xác định thông qua API. Các địa chỉ MAC khác sẽ tự động bị loại bỏ và có thể dẫn đến việc yêu cầu API bị trống một cách hiệu quả. Để biết thông tin chi tiết, hãy xem bài viết Bỏ các điểm truy cập Wi-Fi vô dụng.
`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 WiFi, giá trị dBm thường là -35 hoặc thấp hơn và nằm trong khoảng từ -128 đến -10 dBm. Hãy nhớ thêm 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 trên độ nhiễu hiện tại được đo bằng dB.

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

{
  "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 tệp JSON sau đây 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 để 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.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 đượ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 đầu vào. Nếu sau khi lọc, chúng tôi 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ể áp 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à độ chính xác cũng như các yêu cầu về 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 chỉ ra các giải pháp giảm thiểu mà bạn có thể (với tư cách là kỹ sư ứng dụng) sẽ áp 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ẽ 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 rằng bit ít quan trọng thứ hai trong byte quan trọng nhất của macAddress là 0, 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 cần được bộ lọc này loại trừ.

Phạm vi của đị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 để quản lý mạng cũng như các chức năng đa hướng nhằm ngăn việc sử dụng đị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 vào API.

Ví dụ: bạn có thể thu thập địa chỉ MAC có thể sử dụng cho Vị trí địa lý từ một mảng 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');

Khi sử dụng bộ lọc này, danh sách chỉ còn 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à 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 có định dạng JSON xác định vị trí và bán kính.

location: Kinh độ và vĩ độ ước tính của người dùng, tính bằng độ. Chứa một trường phụ lat và một trường phụ lng.
accuracy: Độ chính xác của vị trí ước đoán (tính bằng mét). Thuộc tính 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
}