このページは Cloud Translation API によって翻訳されました。

概要

はじめに

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 オブジェクトの位置情報を特定できないことが確認されました。