Google Maps Geolocation API

概要

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

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

キーの取得 使用制限

Geolocation リクエスト

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

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

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

リクエスト本文

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

  • homeMobileCountryCode:端末のホーム ネットワークのモバイル カントリーコード(MCC)です。
  • homeMobileNetworkCode:端末のホーム ネットワークのモバイル ネットワーク コード(MNC)です。
  • radioType:モバイル端末の無線通信タイプです。サポートされている値は、ltegsmcdmawcdma です。このフィールドはオプションですが、正確な結果を得るために、値が用意されている場合は含めるようにします。
  • carrier:携帯通信会社の名前です。
  • considerIp:WiFi や携帯電話の基地局の信号が利用できない場合に、フォールバックして IP ジオロケーションを使用するかどうかを指定します。リクエスト ヘッダーの IP アドレスは端末の IP ではない場合があることに注意してください。デフォルト値は true です。considerIpfalse に設定すると、フォールバックが無効になります。
  • 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 アドレスです。区切り文字は :(コロン)で、16 進数の各桁には大文字を使用する必要があります。
  • 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 API コンソールで設定されている 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"

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

さらにテストを行う場合は、Android 端末で Network Info II(携帯電話の基地局情報)や WiEye(WiFi アクセス ポイント)を使用して情報を収集することができます。

よくある質問

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

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

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

フィードバックを送信...

Google Maps Geolocation API
Google Maps Geolocation API
ご不明な点がありましたら、Google のサポートページをご覧ください。