Google Maps Geolocation API

概要

Google Maps Geolocation API は、モバイル端末が検出できる携帯電話の基地局や WiFi ノードの情報に基づいて位置と精度半径を返します。ここでは、このデータをサーバーに送信する際のプロトコルや、クライアントに応答が返される際のプロトコルについて説明します。

通信は、HTTPS の POST によって行われなす。リクエストとレスポンスは両方とも JSON 形式で、content-type は application/json です。

Geolocation API を使用した開発を始める前に、認証要件（API キーが必要です）と API の使用制限について確認してください。

Geolocation リクエスト

Geolocation リクエストは、次の URL に POST で送信します。

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

リクエストには、key パラメータの値としてキーを指定する必要があります。key は、アプリケーションの API キーです。このキーを使ってアプリケーションを識別し、割り当て量を管理します。詳細については、キーの取得をご覧ください。

リクエスト本文

リクエスト本文は、JSON 形式で記述します。次のフィールドがサポートされていますが、すべて省略可能です。

homeMobileCountryCode:端末のホームネットワークのモバイルカントリーコード（MCC）です。
homeMobileNetworkCode:端末のホームネットワークのモバイルネットワークコード（MNC）です。
radioType:モバイル端末の無線通信タイプです。サポートされている値は、lte、gsm、cdma、wcdma です。このフィールドはオプションですが、正確な結果を得るために、値が用意されている場合は含めるようにします。
carrier:携帯通信会社の名前です。
considerIp:WiFi や携帯電話の基地局の信号が利用できない場合に、フォールバックして IP ジオロケーションを使用するかどうかを指定します。リクエストヘッダーの IP アドレスは端末の IP ではない場合があることに注意してください。デフォルト値は true です。considerIp を false に設定すると、フォールバックが無効になります。
cellTowers:携帯電話の基地局を表すオブジェクトの配列です。詳細については、次の携帯電話の基地局オブジェクトセクションをご覧ください。
wifiAccessPoints:WiFi アクセスポイントオブジェクトの配列です。詳細については、次の WiFi アクセスポイントオブジェクトセクションをご覧ください。

{
  "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.
  ]
}

携帯電話の基地局オブジェクト

リクエスト本文の cellTowers 配列には、ゼロ個以上の携帯電話の基地局オブジェクトを含めます。

cellId（必須）:セルの一意の識別子です。GSM では Cell ID（CID）、CDMA ネットワークでは Base Station ID（BID）です。WCDMA ネットワークでは、UTRAN/GERAN Cell Identity（UC-Id）を使用します。これは、Radio Network Controller（RNC）と Cell ID を連結した 32 ビットの値です。WCDMA ネットワークで 16 ビットの Cell ID の値のみを指定すると、正しくない結果が返される場合があります。
locationAreaCode（必須）:GSM と WCDMAnetwork では、Location Area Code（LAC）です。CDMA ネットワークでは、Network ID（NID）です。
mobileCountryCode（必須）:携帯電話の基地局のモバイルカントリーコード（MCC）です。
mobileNetworkCode（必須）:携帯電話の基地局のモバイルネットワークコード（MNC）です。これは、GSM と WCDMA では MNC で、CDMA では System ID（SID）です。

次のフィールドは省略可能で、現在は使用されていません。ただし、値が利用できるようになると、使用されるようになる可能性があります。

age:このセルがプライマリであったときからの経過時間（ミリ秒）です。age が 0 の場合、cellId は現在の計測結果を表します。
signalStrength:dBm 単位の無線通信の信号強度です。
timingAdvance:タイミングアドバンス値です。

次に、GSM の携帯電話の基地局オブジェクトの例を示します。

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

次に、WCDMA の携帯電話の基地局オブジェクトの例を示します。

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

WiFi アクセスポイントオブジェクト

リクエスト本文の wifiAccessPoints 配列には、2 つ以上の WiFi アクセスポイントオブジェクトを含める必要があります。macAddress は必須で、その他のフィールドは省略可能です。

macAddress:（必須）WiFi ノードの MAC アドレスです。区切り文字は :（コロン）を使用する必要があります。
signalStrength:dBm で計測した現在の信号強度です。
age:このアクセスポイントが検出されてからの経過時間（ミリ秒）です。
channel:クライアントがアクセスポイントとの通信を行っているチャネルです。
signalToNoiseRatio:dB 単位の現在の信号対雑音比です。

次に、WiFi アクセスポイントオブジェクトの例を示します。

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

Geolocation のレスポンス

Geolocation リクエストが成功すると、位置と半径を示す JSON 形式のレスポンスが返されます。

location:度単位のユーザーの推定の緯度と経度です。lat サブフィールドと lng サブフィールドが 1 つずつ含まれます。
accuracy:メートル単位の推定位置の精度です。これは、指定された location を中心とした円の半径です。

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

エラー

エラーが発生すると、標準形式のエラーレスポンス本体が返され、HTTP ステータスコードにはエラーステータスが設定されます。

レスポンスには、次のキーを持つ 1 つの error オブジェクトを含むオブジェクトが含まれています。

code:レスポンスの HTTP ステータスと同じものです。
message:エラーの簡単な説明です。
errors:発生したエラーの一覧です。各エラーには、エラーのタイプの識別子（reason）と簡単な説明（message）が含まれています。

たとえば、無効な JSON を送信すると、次のエラーが返されます。

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

発生する可能性があるエラーには、次のものがあります。

理由	分類	HTTP ステータスコード	説明
`dailyLimitExceeded`	`usageLimits`	403	1 日あたりのリクエストの上限数を超過しました。
`keyInvalid`	`usageLimits`	400	API キーが Google Maps Geolocation API で有効ではありません。キー全体を指定していることを確認してください。また、API の購入を行っている、または無料分の割り当てを使用するために課金を有効にして API のアクティベーションを行っていることを確認してください。
`userRateLimitExceeded`	`usageLimits`	403	Google API Console で設定されている 1 秒および 1 ユーザーあたりのリクエストの上限数を超過しました。この上限数は、すべてのユーザーに妥当な範囲でアクセスを許可しつつ、1 人または少数のユーザーが 1 日あたりの割り当て量を使い切ってしまうのを防ぐために設定します。
`notFound`	`geolocation`	404	リクエストは有効ですが、結果が返されませんでした。
`parseError`	`global`	400	リクエスト本文が有効な JSON ではありません。各フィールドの詳細については、リクエスト本体のセクションをご覧ください。

サンプルリクエスト

サンプルデータを使って Google Maps Geolocation API を試してみたい場合は、次の JSON をファイルに保存します。

{
  "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
    }
  ]
}

次に、コマンドラインから cURL を使用してリクエストを実行します。

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

上記の MAC アドレスの場合、レスポンスは次のようになります。

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

（API キーをお持ちでない場合は、キーの取得をご覧ください）

追加のテストを行うために情報を収集するには、Android 端末の場合は Google Places API for Android と Android Location API を使用します。iOS 端末の場合は、Google Places API for iOS を使用します。

よくある質問

Geolocation のレスポンスで accuracy の半径が非常に大きいのはなぜですか？

Geolocation のレスポンスで accuracy フィールドが非常に大きい値である場合、サービスは WiFi アクセスポイントや携帯電話の基地局ではなく、リクエストの IP に基づいて位置情報を算出しています。この現象は、有効な携帯電話の基地局やアクセスポイントがない場合や、認識できない場合に発生します。

この問題を切り分けるには、リクエストで considerIp を false に設定します。レスポンスが 404 である場合は、wifiAccessPoints オブジェクトと cellTowers オブジェクトを使った位置情報が検出できなかったことになります。

以上で完了です。

概要