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 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ợ là `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 hãng vận chuyển.
`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 thiếu, trống hoặc không đủ tín hiệu Wi-Fi và tháp trạm phát sóng di độ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 gồm các đối tượng 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 gồm các đối tượng điểm truy cập WiFi.	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 chứa từ 0 đến nhiều đối tượng tháp phát sóng di độ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 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ã di động quốc gia (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 mã nhận dạng khách hàng: 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ị tiến trình 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ã nhận dạng ô 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 như hiện có. 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 số sửa đổ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 tháp phát sóng LTE.

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

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 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 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 phần nội dung yêu cầu phải chứa ít nhất hai đối tượng điểm truy cập Wi-Fi đại diện cho các thiết bị điểm truy cập khác nhau về mặt vật lý. 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. Thông thường, địa chỉ này được gọi là BSS, BSSID hoặc địa chỉ 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ẽ bị loại bỏ mà không cần thông báo và có thể dẫn đến việc yêu cầu API trở nên trống. Để 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 dùng được.
`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. 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à ứ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 để 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.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 đượ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 đó bằng cách đảm bảo rằng bit có giá trị thứ hai ít quan trọng nhất của byte có giá trị quan trọng 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à 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à hệ thống sẽ trả về một phản hồi HTTP 404(notFound).

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