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 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à mã Khoá API. Khoá này xác định ứng dụng của bạn cho các mục đích của hạn mức Google Cloud. 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 nội dung yêu cầu không được đưa vào, kết quả đượ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 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 được sử 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 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 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 nên luôn được đưa vào nếu loại đài phát là mà khách hàng biết đến. Nếu trường này bị bỏ qua, API vị trí địa lý được đặt mặc định là `gsm`, sẽ dẫn đến kết quả không hợp lệ hoặc bằng 0 kết quả nếu loại radio đượ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 nếu thiếu tín hiệu Wi-Fi và trạm phát sóng, trống hoặc không đủ để ước tính vị trí thiết bị.	Giá trị mặc định là `true`. Đặt `considerIp` thành `false` để tránh trường hợp dự phòng.
`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.	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.
  ]
}

Vật thể trong trạm phát sóng

Mảng cellTowers của nội dung yêu cầu chứa từ 0 trở lên của trạm 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 cho `nr`. Xem phần Tính toán cellId ở bên dưới. Phần này cũng liệt kê phạm vi 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 cho các sản phẩm khác loại. Xem phần Tính toán newRadioCellId bên dưới, Bảng 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 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ệ có `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 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ị là sẵn có.

Trường	Loại JSON	Mô tả	Ghi chú
`age`	`number` (`uint32`)	Số mili giây kể từ ô này là ô chính.	Nếu tuổi là 0, `cellId` hoặc `newRadioCellId` đại diện cho hiện tại đo lường.
`signalStrength`	`number` (`double`)	Cường độ tín hiệu sóng vô tuyến được đo bằng dBm.
`timingAdvance`	`number` (`double`)	Chiến lược phát hành đĩa đơn lịch hẹn giờ giá trị.

Đ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ạng cell ID cho API vị trí địa lý.

Mạng GSM (2G) sử dụng Cell ID (CID) 16 bit. Phạm vi hợp lệ: 0–65535.
Mạng CDMA (2G) cũng 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 Nhận dạng di động UTRAN/GERAN (UC-ID), là một số nguyên 28 bit giá trị liên kết Mã nhận dạng bộ điều khiển mạng vô tuyến 12 bit (RNC-ID) và 16 bit Mã nhận dạng ô (CID).
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ị Cell ID 16 bit trong mạng GSM sẽ dẫn đến không chính xác hoặc không có kết quả nào.
Mạng LTE (4G) sử dụng phương thức 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 giá trị nhận dạng Nút B E-UTRAN 20 bit (eNBId) và Mã nhận dạ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ỉ chỉ định giá trị Cell ID 8 bit trong mạng LTE sẽ dẫn đến không chính xác hoặc không có kết quả nào.

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, tuỳ theo quyết định của Google, có thể cắt bớt số để nó nằm trong phạm vi được ghi nhận, suy ra thành radioType hoặc trả về một kết quả NOT_FOUND mà không có bất kỳ trong câu trả lờ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 ô dài hơn 32 bit sẽ sử dụng chuẩn 64 bit Trường newRadioCellId để truyền mã ô của mạng đến API vị trí địa lý.

Mạng NR (5G) vẫn sử dụng công nghệ 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ề đố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 hai hoặc nhiều đối tượng điểm truy cập Wi-Fi hơ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	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 quản lý toàn cầu Có thể định vị địa chỉ MAC thông qua API. Các địa chỉ MAC khác là bị giảm tự động và có thể dẫn đến việc yêu cầu API trở nên hiệu quả trống. Để biết thông tin chi tiết, hãy xem phần Ngừng truy cập Wi-Fi vô ích điểm.
`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 so với độ nhiễu đượ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ý 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 để thực hiện yêu cầu của bạn 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
}

Xoá các điểm truy cập Wi-Fi không dùng đến

Xoá đối tượng điểm truy cập Wi-Fi có các macAddress được quản lý tại địa phương 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, 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, các giải pháp giảm thiểu chẳng hạn như dùng tín hiệu vị trí cũ hơn hoặc điểm truy cập Wi-Fi có tín hiệu yếu hơn có thể được sử dụng. Phương pháp này là sự đánh đổi giữa nhu cầu của ứng dụng về việc ước tính vị trí cũng như độ chính xác và mức độ thu hồi của thông tin đó các yêu cầu liên quan. Các kỹ thuật lọc sau đây minh hoạ cách lọc đầu vào, nhưng không hiển thị các biện pháp giảm thiểu mà bạn có thể làm, vì ứng dụng kỹ sư, hãy chọn đăng ký.

Địa chỉ MAC được quản lý cục bộ không phải là tín hiệu vị trí hữu ích để API và tự động được 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 phần nhỏ nhất thứ hai của byte quan trọng nhất của macAddress là 0, ví dụ: thời gian 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ẽ bị 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 là dành riêng dành cho IANA và thường được dùng cho các chức năng quản lý mạng và phát đa hướng loại bỏ việc các mạng này được dùng làm tín hiệu vị trí. Bạn cũng nên xoá Địa chỉ MAC từ dữ liệu đầu vào đến 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');

Sử dụng bộ lọc này chỉ cho kết quả 1c:34:56:78:9a:bc còn lại trong danh sách. Bởi vì danh sách này có ít hơn 2 địa chỉ MAC WiFi, thì yêu cầu sẽ không thành công và HTTP 404 (notFound) phản hồi sẽ được trả về.

Phản hồ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: Vĩ độ và kinh độ ước tính của người dùng toạ độ, tính bằng độ. Chứa một lat và một lng trường phụ.
accuracy: Độ chính xác của vị trí ước đoán, tại mét. Bán kính của một hình tròn xung quanh hình tròn đã cho location.

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