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 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 là không bắt buộc, trừ phi có quy định khác:

Trường	Loại JSON	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 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 cho GSM, WCDMA, LTE và NR. CDMA sử dụng Mã nhận dạng hệ thống (SID)	Phạm vi hợp lệ cho MNC: 0–999. Phạm vi hợp lệ cho mã nhận dạng khách hàng: 0–32767.
`radioType`	`string`	Loại đài phát thanh 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 bạn phải luôn đưa trường này vào nếu ứng dụng khách biết loại đài. Nếu bạn bỏ qua trường này, API vị trí địa lý sẽ mặc định là `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 không chính xác.
`carrier`	`string`	Tên nhà mạng.
`considerIp`	`boolean`	Chỉ định xem có sử dụng lại tính năng xác định vị trí địa lý qua IP nếu không có tín hiệu Wi-Fi và tháp trạm phát sóng di động, tín hiệu trống hoặc không đủ để ước tính vị trí của thiết bị hay không.	Giá trị mặc định là `true`. Đặt `considerIp` thành `false` để ngăn chặn việc sử dụng phương thức dự phòng.
`cellTowers`	`array`	Một mảng các vật thể tháp phát sóng.	Hãy xem phần Đối tượng tháp phát sóng bên dưới.
`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 WiFi 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.
  ]
}

Đối tượng 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	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 cellId bên dưới. Phần này cũng liệt kê các dải giá trị hợp lệ cho từng loại nút chọn.
`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.
`locationAreaCode`	`number` (`uint32`)	Mã khu vực vị trí (LAC) cho mạng GSM và WCDMA. Mã mạng (NID) cho các 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`, `wcdma` và `lte`: 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`, `lte` và `nr`; 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 cho GSM, WCDMA, LTE và NR. CDMA sử dụng Mã nhận dạng 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ó giá trị.

Trường	Loại JSON	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ẽ đại diện cho một phép đo 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ị mức tăng về thời gian.

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ã di động của 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 nguyên trạng. 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 liền 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 nội dung sửa đổi 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 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ã ô 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 giá trị 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 hoặc nhiều đối tượng điểm truy cập Wi-Fi đại diện cho thiết bị điểm truy cập khác biệt về mặt thực tế. 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	Mô tả	Ghi chú
`macAddress`	`string`	Địa chỉ MAC của nút WiFi. Đị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 hai chấm (`:`). Chỉ có thể xác định địa chỉ MAC được quản lý chung 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 một yêu cầu API trở nên trống hoàn toàn. Để biết thông tin chi tiết, hãy xem phần Loại bỏ các điểm truy cập Wifi không hữu ích.
`signalStrength`	`number` (`double`)	Cường độ tín hiệu hiện tại được đo bằng dBm.	Đối với điểm truy cập Wi-Fi, giá trị dBm thường là -35 trở xuống và dao động từ -128 đến -10 dBm. Nhớ đưa vào cả dấu trừ.
`age`	`number` (`uint32`)	Số mili giây kể từ khi điểm truy cập này được phát hiện.
`channel`	`number` (`uint32`)	Kênh mà ứng dụng đang giao tiếp với điểm truy cập.
`signalToNoiseRatio`	`number` (`double`)	Tỷ lệ tín hiệu trên tạp âm hiện tại được đo bằng dB.

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 để đư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 đó sẽ có dạng như sau:

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

Xoá 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 như vậy bằng cách đảm bảo rằng bit có ý nghĩa nhỏ nhất thứ hai của byte có ý nghĩa nhất của macAddress là 0, ví dụ: 1 bit được 2 biểu thị 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:

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, 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à phản hồi HTTP 404 (notFound) sẽ được trả về.

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
}