Google Maps Geolocation API trả về một vị trí và tọa độ chính xác dựa trên thông tin về các sóng di động và các nút WiFi mà các khách hàng sử dụng điện thoại có thể tìm được. Tài liệu này mô tả các giao thức được sử dụng để gửi dữ liệu đến server và trả lại thông tin cho người dùng.

Việc truyền gửi dữ liệu được thực hiện thông qua HTTPS sử dụng method POST. Cả hai request và respond được định dạng JSON, và kiểu nội dung của cả hai là application / json.

Trước khi bạn bắt đầu phát triển với các Geolocation API, xem xét các yêu cầu chứng thực (bạn cần một mã khóa API) và giới hạn sử dụng API.

Các yêu cầu Geolocation

request Geolocation được gửi bằng method POST và sử dụng URL sau:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY Bạn phải có 1 key đặc biệt trong request của bạn, bao gồm các tham số là 1 cặp giá trị key value. Một khóa là một API key của ứng dụng. Cái này dùng để xác thực ứng dụng của bạn nhằm mục đích quản lý ứng dụng. Click vào đây để biết cách tạo 1 key

Request body

Các request phải có định dạng JSON. Các trường sau đây được hỗ tr``ợ, và tất cả các trường là tùy chọn:

homeMobileCountryCode: Mã quốc gia (MCC) dành cho các thiết bị sử dụng home netwwork. homeMobileNetworkCode: Mã mạng di động (MNC) dành cho các thiết bị sử dụng home netwwork. radioType: Các loại vô tuyến di động. Được hỗ trợ lte, gsm, CDMA và WCDMA. Trong khi các trường này là tùy chọn, nó nên được bao gồm nếu một giá trị có sẵn, cho kết quả chính xác hơn. carrier: Tên carrier. considerIp: Xác định xem các mạng di động hay wifi có tương thích hay không. Lưu ý rằng địa chỉ IP trong request header có thể không phải là IP của thiết bị. Mặc định là đúng. Đặt considerIp false để vô hiệu hóa fall back. cellTowers: Một mảng của các đối tượng mạng di động. Xem các Cell Tower Objects phần dưới đây. wifiAccessPoints: Một mảng của các đối tượng điểm truy cập WiFi. Xem các đối tượng WiFi Access Point phần 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.
  ]
}

Cell tower objects

mảng cellTowers của request body chứa không hoặc nhiều đối tượng cell tower.

CellID (required): định danh duy nhất của cell. Trên GSM, đây là Cell ID (CID); mạng CDMA sử dụng Base Station ID (BID). mạng WCDMA sử dụng UTRAN / GERAN Cell Identity (UC-Id), cái mà là một giá trị 32-bit concatenating Radio Network Controller (RNC) và Cell ID. Xác định chỉ có 16-bit giá trị Cell ID trong mạng WCDMA có thể trả lại kết quả không chính xác. locationAreaCode (required): Mã vùng (LAC) cho GSM và WCDMAnetworks. ID mạng (NID) cho các mạng CDMA. mobileCountryCode (required): Mobile Country Code của cell tower (MCC). mobileNetworkCode (required): Mobile Network Code của cell tower . Đây là MNC cho GSM và WCDMA; CDMA sử dụng ID System (SID). Các trường tùy chọn sau đây hiện không được sử dụng, nhưng có thể được bao gồm nếu giá trị có sẵn.

age: Số mili giây tính từ cell này là chính. Nếu tuổi là 0, CellID đại diện cho một phép đo hiện tại. signalStrength: cường độ tín hiệu vô tuyến đo bằng dBm. timingAdvance: Giá trị advance thời gian. Một ví dụ GSM đối tượng cell tower bên dưới

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

Một ví dụ WCDMA cell tower object bên dưới.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Đối tượng điểm truy cập WiFi

mảng wifiAccessPoints request body của bạn cần phải chứa hai hoặc nhiều đối tượng điểm truy cập WiFi. macAddress được yêu cầu; tất cả các trường khác là tùy chọn.

macAddress: (required) Địa chỉ MAC của nút WiFi. Máy phân tách phải: (dấu hai chấm). signalStrength: Các cường độ tín hiệu hiện tại đo bằng dBm. age: Số mili giây tính từ điểm truy cập này đã được phát hiện. channel: Các kênh mà qua đó khách hàng là giao tiếp với các điểm truy cập. signalToNoiseRatio: Các tín hiệu hiện tại tỷ lệ tiếng ồn đo bằng dB. Một ví dụ đối tượng điểm truy cập WiFi được hiển thị dưới đây.

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Geolocation responses

Một yêu cầu định vị thành công sẽ trả về một phản ứng định dạng JSON xác định một location và radius.

location: Vĩ độ và kinh độ của người sử dụng, tinhs bằng độ. Chứa một trường lat và một trường lng. accuracy: Độ chính xác của location, tính bằng mét. Điều này thể hiện cho các radius của một vòng tròn xung quanh vị trí nhất định.

{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Errors

Trong trường hợp có lỗi, nội dung phản hồi lỗi định dạng tiêu chuẩn sẽ được trả lại và mã trạng thái HTTP sẽ được đặt vào một tình trạng lỗi.

Các respond có chứa một đối tượng với một đối tượng lỗi duy nhất với các phím sau đây:

code: Đây là giống như trạng thái HTTP của đáp ứng. message: Một mô tả ngắn về các lỗi. errors: Một danh sách các lỗi xảy ra. Mỗi lỗi chứa một định danh cho các loại lỗi (lý do) và một mô tả ngắn (tin nhắn). Ví dụ, gửi JSON không hợp lệ sẽ trở lại các lỗi sau đây:

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

Lỗi có thể bao gồm:

Reason Domain HTTP Status Code Mô tả
dailyLimitExceeded usageLimits 403 Bạn đã vượt quá giới hạn hàng ngày của bạn.
keyInvalid usageLimits 400 API key của bạn không hợp lệ đối với Google Maps Geolocation API. Đảm bảo chắc chắn đã bao gồm cả key, và các API đã được mua hoặc đã kích hoạt thanh toán và kích hoạt các API để có được hạn ngạch miễn phí.
userRateLimitExceeded usageLimits 403 Bạn đã vượt quá yêu cầu mỗi giây cho mỗi giới hạn người dùng mà bạn cấu hình trong Bảng điều khiển API của Google. Giới hạn này phải được cấu hình để ngăn chặn một nhóm duy nhất hoặc nhỏ người dùng từ hết hạn ngạch 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.
notFound geolocation 404 Yêu cầu là hợp lệ, nhưng không có kết quả được trả về.
parseError global 400 Các request body không đúng định dạng JSON. Tham khảo phần Request Body thông tin chi tiết về từng trường.

Sample requests

Lưu ý: các đị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ừ các API.

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "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"

Cácrespond cho các địa chỉ Mac trên trông như thế này:

{
  "location": {
    "lat": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}