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