概要

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

はじめに

Geolocation API は、モバイル クライアントが検出できる基地局や Wi-Fi ノードの情報に基づいて、現在地と精度範囲を返します。このドキュメントでは、このデータをサーバーに送信し、クライアントにレスポンスを返すために使用されるプロトコルについて説明します。

POST によって HTTPS 経由で通信が行われます。リクエストとレスポンスはどちらも JSON 形式で、コンテンツ タイプは 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 形式にする必要があります。リクエスト本文が含まれていない場合は、リクエストの場所の IP アドレスに基づいて結果が返されます。次のフィールドがサポートされています。特に明記されていない限り、すべてのフィールドはオプションです。

フィールド JSON 型 説明 備考
homeMobileCountryCode number（uint32） デバイスのホーム ネットワークのモバイル カントリー コード（MCC）。 radioType gsm（デフォルト）、wcdma、lte、nr で対応。cdma では使用されません。
有効な範囲: 0 ～ 999。
homeMobileNetworkCode number（uint32） デバイスのホーム ネットワークのモバイル ネットワーク コードです。 GSM、WCDMA、LTE、NR の MNC です。
CDMA はシステム ID（SID）を使用します。		 MNC の有効な範囲: 0 ～ 999。
SID の有効な範囲: 0 ～ 32767。
radioType string モバイル ラジオのタイプ。サポートされている値は gsm、cdma、wcdma、lte、nr です。 このフィールドはオプションですが、クライアントが無線のタイプを認識している場合は必ず含める必要があります。
このフィールドを省略すると、Geolocation API はデフォルトで gsm に設定されます。この場合、想定するラジオボタンのタイプが正しくない場合、無効またはゼロになります。
carrier string 携帯通信会社の名前です。
considerIp boolean Wi-Fi や基地局の信号がない、空である、またはデバイスの位置情報を推定するのに十分でない場合に、IP の位置情報にフォールバックするかどうかを指定します。 デフォルトは true です。considerIp を false に設定して、フォールバックを無効にします。
cellTowers array 携帯電話の基地局を表すオブジェクトの配列です。 以下の基地局オブジェクト セクションをご覧ください。
wifiAccessPoints array WiFi アクセス ポイント オブジェクトの配列です。 以下の Wi-Fi アクセス ポイント オブジェクト セクションをご覧ください。

Geolocation API リクエストの本文の例を以下に示します。

{
  "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 配列には、0 個以上の基地局オブジェクトが含まれています。

フィールド JSON 型 説明 備考
cellId number（uint32） セルの一意の識別子です。 radioType gsm（デフォルト）、cdma、wcdma、lte では必須です。nr の場合は拒否されます。
下記のセル ID の計算のセクションをご覧ください。各ラジオボタンの有効な値の範囲も示しています。
newRadioCellId number（uint64） NR（5G）セルの一意の識別子。 radioType nr には必須です。他のタイプの場合は拒否されます。
下記の新しいラジオセル ID の計算セクションをご覧ください。このフィールドの有効な値の範囲も示されています。
locationAreaCode number（uint32） GSM ネットワークと WCDMA ネットワークのロケーション エリア コード（LAC）。
CDMA ネットワークのネットワーク ID（NID）。
LTE ネットワークと NR ネットワークのトラッキング エリア コード（TAC）。		 radioType gsm（デフォルト）と cdma（必須、その他値）は必須です。
有効な範囲は gsm、cdma、wcdma、lte: 0 ～ 65535 です。
有効な範囲は nr: 0 ～ 16777215 です。
mobileCountryCode number（uint32） 基地局のモバイル カントリー コード（MCC）。 radioType gsm（デフォルト）、wcdma、lte、nr には必須です。cdma には使用されません。
有効な範囲: 0 ～ 999。
mobileNetworkCode number（uint32） 基地局のモバイル ネットワーク コード。 GSM、WCDMA、LTE、NR の MNC です。
CDMA はシステム ID（SID）を使用します。		 必須。
MNC の有効な範囲: 0 ～ 999。
SID の有効な範囲: 0 ～ 32767。

次のオプション フィールドは現在使用されていませんが、値を使用できる場合は使用できます。

フィールド JSON 型 説明 備考
age number（uint32） このセルがプライマリであったときからの経過時間（ミリ秒）です。 age が 0 の場合、cellId または newRadioCellId は現在の測定値を表します。
signalStrength number（double） dBm 単位の無線通信の信号強度です。
timingAdvance number（double） タイミングの詳細値。

cellId を計算しています

NR（5G）より前の無線通信タイプでは、32 ビットの cellId フィールドを使用してネットワーク セル ID を Geolocation API に渡します。

  • GSM（2G）ネットワークでは、16 ビットのセル ID（CID）がそのまま使用されます。有効な範囲は 0 ～ 65535 です。
  • CDMA（2G）ネットワークでは、16 ビットの Base Station ID（BID）がそのまま使用されます。有効な範囲は 0 ～ 65535 です。
  • WCDMA（3G）ネットワークでは、UTRAN/GERAN Cell Identity（UC-ID）を使用します。これは、12 ビットの Radio Network Controller Identifier（RNC-ID）と 16 ビットの Cell ID（CID）を連結した 28 ビットの整数値です。
    数式: rnc_id << 16 | cid。
    有効な範囲: 0 ～ 268435455。
    注: WCDMA ネットワークで 16 ビットのセル ID 値のみを指定すると、結果が正しくないか、ゼロになります。
  • LTE（4G）ネットワークでは、E-UTRAN セル ID（ECI）を使用します。これは、20 ビットの E-UTRAN ノード B 識別子（eNBId）と 8 ビットのセル ID（CID）を連結した 28 ビットの整数値です。
    数式: enb_id << 8 | cid。
    有効な範囲: 0 ～ 268435455。
    注: LTE ネットワークで 8 ビットのセル ID 値のみを指定した場合、誤った結果やゼロの結果が返されます。

これらの範囲外の値を API リクエストに配置すると、未定義の動作が発生する可能性があります。API は、Google の裁量により、ドキュメントの範囲に収まるように数値を切り捨てたり、radioType に対する修正を推測したり、レスポンスにインジケーターなしで NOT_FOUND の結果を返す場合があります。

LTE 基地局オブジェクトの例を以下に示します。

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

newRadioCellId を計算しています

セル ID が 32 ビットを超える新しいネットワークでは、64 ビットの newRadioCellId フィールドを使用してネットワーク セル ID を Geolocation API に渡します。

  • NR（5G）ネットワークでは、36 ビットの New Radio Cell Identity（NCI）をそのまま使用します。
    有効な範囲: 0 ～ 68719476735。

NR 基地局オブジェクトの例を以下に示します。

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

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

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

フィールド JSON 型 説明 備考
macAddress string Wi-Fi ノードの MAC アドレス。一般には BSS、BSSID、MAC アドレスと呼ばれます。 必須。:（コロン）区切りの 16 進数文字列。
signalStrength number（double） dBm で計測した現在の信号強度です。 Wi-Fi アクセス ポイントの場合、dBm 値は通常 -35 以下、範囲は -128 ～-10 dBm です。マイナス記号は必ず含めてください。
age number（uint32） このアクセス ポイントが検出されてからの経過時間（ミリ秒）です。
channel number（uint32） クライアントがアクセス ポイントとの通信を行っているチャネルです。
signalToNoiseRatio number（double） 現在の信号対雑音比（dB で測定）。

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

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

Geolocation のレスポンス

位置情報の取得リクエストが成功すると、位置と半径を指定した JSON 形式のレスポンスが返されます。

  • location: ユーザーの推定の緯度と経度（度単位）。1 つの lat サブフィールドと 1 つの lng サブフィールドがある。
  • accuracy: 推定位置情報の精度（メートル単位）。これは、指定された location を中心とした円の半径を表します。
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

エラー

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

レスポンスには、次のキーを持つ単一の 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 キーは Geolocation API に対して有効ではありません。キー全体を含めていること、API を購入しているか、API を有効にして課金を有効にし、無料の割り当てを取得していることを確認してください。
userRateLimitExceeded usageLimits 403 Google Cloud Console で構成したリクエストの上限を超えています。この上限は通常、1 日あたりのリクエスト数、100 秒あたりのリクエスト数、ユーザーごとの 100 秒あたりのリクエスト数として設定されます。この上限は、1 つまたは少数のユーザーが 1 日の割り当て量を使い切るのを防止しながら、すべてのユーザーに相応のアクセス権を付与するように構成する必要があります。これらの上限を構成するには、API 使用量の上限設定をご覧ください。
notFound geolocation 404 リクエストは有効ですが、結果が返されませんでした。
parseError global 400 リクエストの本文は有効な JSON ではありません。各フィールドの詳細については、リクエストの本文をご覧ください。

サンプル リクエスト

Geolocation API のサンプルデータを試す場合は、次の JSON をファイルに保存します。

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

その後、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": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

（API キーがない場合は、API キーを取得するをご覧ください）。

追加のテストを行うために、Places SDK for Android と Android Location API を使用して Android デバイスから情報を収集し、Places SDK for iOS を使用して iOS デバイスから情報を収集できます。

よくある質問

Geolocation のレスポンスで、非常に大きな accuracy 半径が返されるのはなぜですか？

位置情報レスポンスの accuracy フィールドに非常に大きな値が表示されている場合、Wi-Fi ポイントや基地局ではなく、リクエスト IP に基づいて位置情報サービスの位置が指定された可能性があります。これは、基地局やアクセス ポイントが有効または認識されない場合に発生することがあります。

これが問題であることを確認するには、リクエストで considerIp を false に設定します。レスポンスが 404 の場合、wifiAccessPoints オブジェクトと cellTowers オブジェクトの位置情報を特定できないことが確認されました。