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 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 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 là JSON. Nếu không đưa nội dung yêu cầu vào, thì 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:

Kỹ thuật	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 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 đài phát dành cho thiết bị di động. Các giá trị được hỗ trợ: `gsm`, `cdma`, `wcdma`, `lte` và `nr`.	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 xác định loại đài phát. Nếu trường này bị bỏ qua, API vị trí địa lý mặc định là `gsm`. Theo đó, sẽ dẫn đến kết quả không hợp lệ hoặc không có kết quả nếu loại đài phát đượ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 định vị vị trí IP khi Wi-Fi và tín hiệu 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 chặn hoạt động quay lại.
`cellTowers`	`array`	Một mảng các vật thể tháp phát sóng.	Xem phần Đối tượng Tháp điện thoại di động bên dưới.
`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 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.

Kỹ thuật	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`. Xem phần Tính toán cellId ở bên dưới. Phần này cũng liệt kê các phạm vi giá trị hợp lệ cho mỗi 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. 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 mạng GSM và GSM. Mã mạng (NID) cho các mạng CDMA. Mã vùng 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. Dải ô hợp lệ với `gsm`, `cdma`, `wcdma` và `lte`: 0–65535. Dải ô hợp lệ với `nr`: 0–16777215.
`mobileCountryCode`	`number` (`uint32`)	Mã quốc gia dành cho thiết bị 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, GSM, 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ó sẵn giá trị.

Kỹ thuật	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ẽ biểu thị số đo hiện tại.
`signalStrength`	`number` (`double`)	Cường độ tín hiệu sóng vô tuyến được đo bằng dBm.
`timingAdvance`	`number` (`double`)	Giá trị tăng trước thời gian.

Đang tính `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) cũng sử dụng mã nhận dạng điện thoại di động (CID) 16 bit. Phạm vi hợp lệ: 0 – 65535.
Mạng CDMA (2G) sử dụng ID 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à giá trị số nguyên 28 bit liên kết Mã nhận dạng bộ điều khiển mạng vô tuyến (RNC-ID) 16 bit với Mã nhận dạng di động (CID) 16 bit.
Công thức: rnc_id << 16 | cid.
Dải ô hợp lệ: 0–268435455.
Lưu ý: Việc chỉ chỉ định giá trị Mã nhận dạng ô 16 bit trong mạng GSM sẽ dẫn đến kết quả không chính xác hoặc bằng không.
Mạng LTE (4G) sử dụng Mã nhận dạng mạng di động E-UTRAN (ECI), là một giá trị số nguyên 28 bit liên kết mã nhận dạng nút B E-UTRAN 20 bit (eNBId) và Mã nhận dạng di động (CID) 8 bit.
Công thức: enb_id << 8 | cid.
Dải ô hợp lệ: 0–268435455.
Lưu ý: Việc chỉ chỉ định giá trị Cell ID 8 bit trong các mạng LTE sẽ dẫn đến kết quả không chính xác hoặc bằng không.

Việc đặt các giá trị bên ngoài những 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 riêng của Google, API có thể cắt bớt số để vừa với phạm vi được ghi nhận, dự đoán một sự điều chỉnh 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ể trạm 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 mạng di động dài hơn 32 bit sẽ sử dụng trường newRadioCellId 64 bit để truyền mã mạng di động của mạng đến Geolocation API.

Mạng NR (5G) vẫn sử dụng công nghệ Nhận dạng sóng vô tuyến mới (NCI) 36 bit nguyên trạng.
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.

Kỹ thuật	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 (`:`). Bạn chỉ có thể xác định các địa chỉ MAC được quản lý toàn cầu 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 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 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ớ đư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à máy khách đ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.

Dưới đây là một 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ý với dữ liệu mẫu, hãy lưu tệp JSON sau:

{
  "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 đó có dạng như sau:

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

Bỏ các điểm truy cập Wi-Fi không sử dụng

Việc xoá các đối tượng điểm truy cập Wi-Fi bằng 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, hệ thống có thể xác định được rằng lệnh gọi API vị trí địa lý sẽ không thành công, thì người dùng 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ũ hơn 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ới độ chính xác và các yêu cầu về việc gọi lại của ứng dụng. 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ể, với tư cách là kỹ sư ứng dụng, sẽ 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 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à một 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 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 các chức năng quản lý mạng cũng như các chức năng phát đa hướng, trong đó loại trừ việc 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 vào API.

Ví dụ: bạn có thể thu thập các đị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 sẽ chỉ còn 1c:34:56:78:9a:bc. 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ề.

Phản hồi về vị trí địa lý

Một 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: Vĩ độ và kinh độ ướ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 thể hiện 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
}