Tổng quan

Trước khi bắt đầu: Trước khi bắt đầu sử dụng API Vị trí địa lý, bạn cần có dự án có tài khoản thanh toán và API Vị trí địa lý đã bật. Bạn nên tạo nhiều Chủ sở hữu dự án và Quản trị viên thanh toán để nhóm của bạn luôn có người có vai trò này. Để tìm hiểu thêm, hãy xem phần Thiết lập trong Cloud Console.

Giới thiệu

Location API trả về vị trí và bán kính chính xác dựa trên thông tin về trạm phát sóng và nút Wi-Fi mà ứng dụng di động có thể phát hiện. Tài liệu này mô tả giao thức dùng để gửi dữ liệu này đến máy chủ và trả về phản hồi cho ứng dụng.

Việc giao tiếp được thực hiện qua HTTPS bằng POST. Cả yêu cầu và phản hồi đều được định dạng dưới dạng JSON và loại nội dung của cả hai là application/json.

Trước khi bạn bắt đầu

Trước khi bắt đầu phát triển bằng API vị trí địa lý, hãy xem lại các yêu cầu xác thực (bạn cần một khóa API) và thông tin về việc sử dụng và thanh toán API (bạn cần bật tính năng thanh toán trên dự án của mình).

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 tới URL sau:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Bạn phải chỉ định một khóa trong yêu cầu của mình, trong đó có bao gồm một giá trị của thông số key. key là khoá API của ứng dụng. Khoá này xác định ứng dụng của bạn nhằm mục đích quản lý hạn mức. Tìm hiểu cách nhận 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 phần nội dung yêu cầu không được đưa vào, 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ừ khi có quy định khác:

Trường	Loại JSON	Mô tả	Ghi chú
homeMobileCountryCode	number (uint32)	Mã quốc gia trên thiết bị di động (MCC) cho mạng 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 chính của thiết bị. Đây là MNC của GSM, SWIFT, 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 thanh di động. Giá trị được hỗ trợ là gsm, cdma, wcdma, lte và nr.	Mặc dù trường này là không bắt buộc, nhưng bạn phải luôn bao gồm trường này nếu ứng dụng biết loại đài phát. Nếu trường này bị bỏ qua, thì API Location sẽ đặt giá trị mặc định là gsm. Kết quả là sẽ dẫn đến kết quả không hợp lệ hoặc kết quả bằng 0 nếu loại radio được cho là không chính xác.
carrier	string	Tên nhà mạng.
considerIp	boolean	Chỉ định xem có quay lại vị trí địa lý IP hay không nếu tín hiệu Wi-Fi và trạm phát sóng di động bị thiếu, 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 để tắt tính năng quay lại.
cellTowers	array	Một mảng các đối tượng của ô di động.	Hãy xem phần Đối tượng của trạm 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.	Xem mục Đối tượng điểm truy cập Wi-Fi dưới đây.

Nội dung yêu cầu API Vị trí địa lý ví dụ được hiển thị dưới đây.

{
  "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 của trạm phát sóng

Mảng cellTowers của nội dung yêu cầu chứa không có hoặc có đối tượng tháp di động trở lên.

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 ô tính toán (IdId) dưới đây. Phần này cũng liệt kê các phạm vi giá trị hợp lệ cho từng loại đài.
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 này.
locationAreaCode	number (uint32)	Mã vùng vị trí (LAC) cho mạng GSM và SWIFT. 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 trên 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 được sử 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 của GSM, SWIFT, LTE và NR. CDMA sử dụng Mã 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.

Những trường không bắt buộc sau đây hiện không được sử dụng, nhưng có thể được đưa vào nếu có cá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 là giá trị đo lường 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ị thời gian đặt trước.

Đang tính cellId

Các loại đài trước NR (5G) sử dụng trường cellId 32 bit để chuyển mã nhận dạng ô mạng đến API vị trí địa lý.

• Mạng GSM (2G) sử dụng đúng ID di động (CID) 16 bit. Phạm vi hợp lệ: 0–65535.
• Mạng CDMA (2G) sử dụng mã trạm cơ sở 16 bit (BID). Phạm vi hợp lệ: 0–65535.
• Mạng Quảng cáo di động UTRAN/GERAN (UC-ID) là giá trị nhận dạng ô 28 bit/20 bit, dùng để kết hợp Mã nhận dạng bộ điều khiển mạng vô tuyến (RNC-ID) và mã nhận dạng điện thoại di động 16 bit (CIDC).
  Công thức: rnc_id << 16 | cid.
  Phạm vi hợp lệ: 0–268435455.
  Lưu ý: Nếu bạn chỉ định giá trị Mã nhận dạng ô 16 bit trong các mạng SWIFT thì kết quả sẽ không chính xác hoặc không có kết quả.
• 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 liền Mã nhận dạng nút E-UTRAN 20 bit (eNBId) và Mã nhận dạng điện thoại di động 8 bit (CID).
  Công thức: enb_id << 8 | cid.
  Phạm vi hợp lệ: 0–268435455.
  Lưu ý: Nếu bạn chỉ định giá trị Mobile ID 8 bit trong các mạng LTE, kết quả sẽ không chính xác hoặc bằng 0.

Việc đặt 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. Theo quyết định của Google, API có thể cắt bớt số đó cho phù hợp với phạm vi tài liệu, suy ra sửa đổi 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à một ví dụ về đối tượng trong 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ử 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 đúng danh tính Di động vô tuyến mới (NCI) 36 bit.
  Phạm vi hợp lệ: 0–68719476735.

Dưới đây là một ví dụ về đối tượng của trạm phát sóng NR.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

Đối tượng của đ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. 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 : (dấu hai chấm)
signalStrength	number (double)	Cường độ tín hiệu hiện tại đo bằng dBm.	Đối với điểm truy cập Wi-Fi, giá trị dBm thường từ -35 trở xuống và nằm trong khoả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à khách hàng đang giao tiếp với điểm truy cập.
signalToNoiseRatio	number (double)	Tín hiệu hiện tại so với tỷ lệ nhiễu được đo bằng dB.

Dưới đây là ví dụ về đối tượng điểm truy cập Wi-Fi.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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, theo độ. Chứa một trường con lat và một lng.
• accuracy: Độ chính xác của vị trí ước tính, tính bằng mét. Giá trị này đại diện cho 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
}

Lỗi

Trong trường hợp xảy ra lỗi, phần nội dung phản hồi lỗi định dạng chuẩn sẽ được trả về và mã trạng thái HTTP sẽ được đặt thành trạng thái lỗi.

Phản hồi chứa một đối tượng có một đối tượng error duy nhất bằng các khoá sau:

• code: Trạng thái này giống với trạng thái HTTP của phản hồi.
• message: Nội dung mô tả ngắn về lỗi.
• errors: Danh sách các lỗi đã xảy ra. Mỗi lỗi chứa một giá trị nhận dạng cho loại lỗi (reason) và một nội dung mô tả ngắn (message).

Ví dụ: việc gửi JSON không hợp lệ sẽ trả về lỗi sau:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Các lỗi có thể xảy ra bao gồm:

Lý do	Lâu đài	Mã trạng thái HTTP	Mô tả
dailyLimitExceeded	usageLimits	403	Bạn đã vượt quá hạn mức hằng ngày.
keyInvalid	usageLimits	400	Khóa API của bạn không hợp lệ cho API Vị trí địa lý. Hãy đảm bảo rằng bạn đã cung cấp toàn bộ khoá và bạn đã mua API hoặc đã bật tính năng thanh toán và kích hoạt API này để lấy hạn mức API miễn phí.
userRateLimitExceeded	usageLimits	403	Bạn đã vượt quá giới hạn yêu cầu mà bạn đã định cấu hình trong Google Cloud Console. Giới hạn này thường được đặt là số yêu cầu mỗi ngày, số yêu cầu mỗi 100 giây và số yêu cầu trên 100 giây/người dùng. Bạn nên định cấu hình giới hạn này để ngăn một nhóm nhỏ hoặc một người dùng sử dụng hết hạn mức hằng ngày của bạn, trong khi vẫn cho phép tất cả người dùng truy cập hợp lý. Hãy xem bài viết Sử dụng API giới hạn để định cấu hình các giới hạn này.
notFound	geolocation	404	Yêu cầu này hợp lệ, nhưng không có kết quả nào được trả về.
parseError	global	400	Nội dung yêu cầu không phải là JSON hợp lệ. Hãy tham khảo phần Nội dung yêu cầu để biết thông tin chi tiết về từng trường.

Yêu cầu mẫu

Lưu ý: Địa chỉ Mac có thể thay đổi theo thời gian. Vì lý do đó, các ví dụ trên trang này có thể dẫn đến một thông báo lỗi từ API.

Nếu bạn muốn dùng thử API vị trí địa lý bằng dữ liệu mẫu, hãy lưu tệp JSON sau vào một tệp:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "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ên có dạng như sau:

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

(Xem Nhận khóa API nếu bạn không có khóa API.)

Để thử nghiệm thêm, bạn có thể thu thập thông tin từ thiết bị Android bằng cách sử dụng SDK Địa điểm cho Android và API Vị trí Android cũng như từ thiết bị iOS bằng SDK Địa điểm cho iOS.

Câu hỏi thường gặp

Tại sao tôi nhận được bán kính accuracy rất lớn trong phản hồi Vị trí địa lý của mình?

Nếu phản hồi Vị trí địa lý của bạn thể hiện giá trị rất cao trong trường accuracy, thì dịch vụ có thể đang định vị địa lý dựa trên IP yêu cầu, thay vì điểm phát Wi-Fi hoặc trạm phát sóng. Điều này có thể xảy ra nếu không có trạm phát sóng hoặc điểm truy cập nào hợp lệ hoặc được nhận dạng.

Để xác nhận rằng đây là vấn đề, hãy đặt considerIp thành false trong yêu cầu của bạn. Nếu phản hồi là 404, bạn đã xác nhận rằng không thể định vị vị trí địa lý của các đối tượng wifiAccessPoints và cellTowers.