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ị địa lý

Yêu cầu định vị địa lý được gửi bằng 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, đượ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 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:

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 nhà của thiết bị. Đây là mã mạng di động (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 SID: 0–32767.
`radioType`	`string`	Loại sóng vô tuyến 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 nên luôn thêm trường này nếu ứng dụng biết loại đài phát. Nếu bạn bỏ qua trường này, Geolocation API sẽ mặc định là `gsm`, 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 hãng vận chuyển.
`considerIp`	`boolean`	Chỉ định xem có quay lại vị trí địa lý dựa trên 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` để ngăn quay lại.
`cellTowers`	`array`	Một mảng gồm các đối tượng trạm phát sóng.	Hãy xem phần Đối tượng trạm 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 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 của Geolocation API.

{
  "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 trong nội dung yêu cầu chứa từ 0 trở lên đối tượng trạm phát sóng.

Trường	Loại JSON	Mô tả	Ghi chú
`cellId`	`number` (`uint32`)	Giá trị nhận dạng riêng biệ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 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 đài.
`newRadioCellId`	`number` (`uint64`)	Giá trị nhận dạng riêng biệ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ã vùng 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ã quốc gia cho nhà cung cấp dịch vụ 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 dành cho GSM, WCDMA, 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 dùng, nhưng bạn có thể thêm 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` biểu thị một phép đo hiện tại.
`signalStrength`	`number` (`double`)	Cường độ tín hiệu vô tuyến đo bằng dBm.
`timingAdvance`	`number` (`double`)	Giá trị độ trễ.

Đang tính toán `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 Cell ID (CID) 16 bit nguyên trạng. Phạm vi hợp lệ: 0 – 65535.
Mạng CDMA (2G) sử dụng Mã nhận dạng trạm gốc (BID) 16 bit. Phạm vi hợp lệ: 0 – 65535.
Mạng WCDMA (3G) sử dụng Giá trị nhận dạng ô UTRAN/GERAN (UC-ID), 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à Giá trị 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ỉ định giá trị Cell ID 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ã 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ỉ đị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 các giá trị bên ngoài các dải 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 này có thể cắt bớt số để phù hợp với phạm vi được ghi lại, suy ra một nội dung chỉnh sửa 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ề một đối tượng trạm phát sóng LTE, nằm trong 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 đó sẽ có dạng như sau:

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

Đang tính toán `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ý.

Mạng NR (5G) sử dụng Mã nhận dạng ô vô tuyến mới (NCI) 36 bit.
Phạm vi hợp lệ: 0 – 68719476735.

Dưới đây là ví dụ về một đối tượng trạm phát sóng NR, nằm trong phần 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 đó sẽ 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 trong nội dung yêu cầu phải chứa từ 2 đối tượng điểm truy cập Wi-Fi trở lên, đại diện cho các thiết bị điểm truy cập cố định khác biệt về mặt vật lý. Bạn bắt buộc phải điền vào trường macAddress. 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 động, chẳng hạn như các điểm truy cập trên máy bay và tàu hoả.

Trường	Loại JSON	Mô tả	Ghi chú
`macAddress`	`string`	Địa chỉ MAC của nút WiFi. Nó thường đượ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ể định vị các địa chỉ MAC được quản lý chung bằng API. Các địa chỉ MAC khác sẽ bị loại bỏ một cách âm thầm và có thể khiến yêu cầu API trở nên trống rỗng. Để biết chi tiết, hãy xem Loại bỏ các điểm truy cập Wifi không cần thiết.
`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 chắc chắn bao gồm dấu trừ. Đối với các giá trị lớn hơn -10 dBm, API trả về `NOT FOUND`.
`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à máy khách đ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.

Một ví dụ về đối tượng điểm truy cập WiFi, là một phần của nội dung yêu cầu, được hiển thị 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 đó sẽ 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ử Geolocation API 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 để thực hiện 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ó macAddresses đượ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 Geolocation 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 một lệnh gọi Geolocation API 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. Cách tiếp cận này là sự đánh đổi giữa nhu cầu của ứng dụng về thông tin ước đoán vị trí và 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 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ó 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 thứ hai của byte có nghĩa nhất của macAddress là 0, ví dụ: bit 1 đượ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à 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.

Dải đị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 được dùng cho các chức năng quản lý mạng và truyền tin đa hướng, điều này ngăn cả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 các địa chỉ MAC có thể sử dụng cho Dịch vụ 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');

Khi sử dụng bộ lọc này, danh sách chỉ còn lại 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à một 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 định vị đị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: Vĩ độ và kinh độ ước tính của người dùng, tính bằng độ. Chứa một 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 vòng tròn xung quanh location đã cho.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Yêu cầu và phản hồi vị trí địa lý Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Yêu cầu định vị địa lý

Nội dung yêu cầu

Đối tượng trạm phát sóng

Đang tính toán cellId

Đang tính toán newRadioCellId

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

Yêu cầu mẫu

Loại bỏ các điểm truy cập Wi-Fi không dùng đến

Câu trả lời về vị trí địa lý

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

Đang tính toán `cellId`

Đang tính toán `newRadioCellId`