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 では拒否です。下記の cellId の計算セクションを参照してください。ここには、各ラジオボタンタイプの有効な値の範囲も記載されています。 |
newRadioCellId |
number (uint64 ) |
NR(5G)セルの一意の識別子。 | radioType nr では必須。他の型では拒否されます。フィールドの有効な値の範囲もリストされている、以下の newRadioCellId の計算セクションをご覧ください。 |
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 ) |
このセルがプライマリであったときからの経過時間(ミリ秒)です。 | 経過時間が 0 の場合、cellId または newRadioCellId は現在の測定値を表します。 |
signalStrength |
number (double ) |
dBm 単位の無線通信の信号強度です。 | |
timingAdvance |
number (double ) |
タイミング アドバンスの値。 |
cellId
を計算しています
NR(5G)より前の無線タイプでは、32 ビットの cellId
フィールドを使用してネットワーク セル ID を Geolocation API に渡します。
- GSM(2G)ネットワークでは、16 ビットの Cell ID(CID)をそのまま使用します。有効範囲: 0 ~ 65535。
- CDMA(2G)ネットワークでは、16 ビットのベースステーション ID(BID)をそのまま使用します。有効範囲: 0 ~ 65535。
- WCDMA(3G)ネットワークは UTRAN/GERAN Cell Identity(UC-ID)を使用します。UC-ID は、12 ビットの無線ネットワーク コントローラ識別子(RNC-ID)と 16 ビットのセル ID(CID)を連結した 28 ビットの整数値です。
数式:rnc_id << 16 | cid
。
有効範囲: 0 ~ 268435455。
注: WCDMA ネットワークで 16 ビットの Cell ID 値のみを指定すると、結果は不正確またはゼロになります。 - LTE(4G)ネットワークは E-UTRAN Cell Identity(ECI)を使用します。ECI は、20 ビットの E-UTRAN Node B Identifier(eNBId)と 8 ビットの Cell ID(CID)を連結した 28 ビットの整数値です。
数式:enb_id << 8 | cid
。
有効範囲: 0 ~ 268435455。
注: LTE ネットワークで 8 ビットの Cell 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 進数文字列。
API を使用して特定できるのは、普遍的に管理される MAC アドレスのみです。その他の MAC アドレスは通知なく破棄されるため、API リクエストが実質的に空になる可能性があります。詳しくは、不要な Wifi アクセス ポイントの削除をご覧ください。 |
signalStrength |
number (double ) |
dBm で計測した現在の信号強度です。 | Wi-Fi アクセス ポイントの場合、dBm 値は通常 -35 以下で、範囲は -128 ~-10 dBm です。必ずマイナス記号を含めてください。 |
age |
number (uint32 ) |
このアクセス ポイントが検出されてからの経過時間(ミリ秒)です。 | |
channel |
number (uint32 ) |
クライアントがアクセス ポイントとの通信を行っているチャネルです。 | |
signalToNoiseRatio |
number (double ) |
現在の信号対雑音比(dB 単位)。 |
次に、WiFi アクセス ポイント オブジェクトの例を示します。
{ "macAddress": "f0:d5:bf:fd:12:ae", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
サンプル リクエスト
サンプルデータを使用して Geolocation API を試す場合は、次の JSON をファイルに保存します。
{ "considerIp": "false", "wifiAccessPoints": [ { "macAddress": "3c:37:86:5d:75:d4", "signalStrength": -35, "signalToNoiseRatio": 0 }, { "macAddress": "30:86:2d:c4:29:d0", "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.4241173, "lng": -122.0915717 }, "accuracy": 20 }
未使用の Wi-Fi アクセス ポイントのドロップ
ローカルで管理されている macAddress
を含む Wi-Fi アクセス ポイント オブジェクトを削除すると、Wi-Fi を入力として使用する Geolocation API 呼び出しの成功率が向上する可能性があります。フィルタリング後に、Geolocation API 呼び出しが成功しないと判断できる場合は、古い位置情報信号や信号が弱い Wi-Fi AP を使用するなどの緩和策を使用できます。このアプローチは、アプリでの位置情報の推定ニーズと、適合率や再現率の要件とのトレードオフとなります。以下のフィルタリング手法は、入力をフィルタする方法を示していますが、アプリケーション エンジニアが適用する緩和策は表示されません。
ローカル管理される MAC アドレスは、API にとって有用なロケーション シグナルではなく、通知なくリクエストから除外されます。このような MAC アドレスを削除するには、macAddress
の最上位バイトの 2 番目に最下位のビットを 0
にします(例: 02:00:00:00:00:00
の 2
で表される 1 ビット)。ブロードキャスト MAC アドレス(FF:FF:FF:FF:FF:FF
)は、このフィルタで効果的に除外できる MAC アドレスの例です。
00:00:5E:00:00:00
~00:00:5E:FF:FF:FF
の MAC アドレスの範囲は IANA 用に予約されており、ネットワーク管理や、位置信号としての使用を妨げるマルチキャスト機能によく使用されます。また、API への入力からこれらの MAC アドレスを削除する必要もあります。
たとえば、位置情報で使用可能な MAC アドレスは、macs
という名前の macAddress
文字列の配列から収集できます。
String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"}; ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs)); _macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16)) && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'] macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']; macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16)) && m.substr(0, 8).toUpperCase() !== '00:00:5E');
このフィルタを使用すると、1c:34:56:78:9a:bc
のみがリストに残ります。このリストに含まれる Wi-Fi MAC アドレスは 2 個未満であるため、リクエストは成功せず、HTTP 404 (notFound
)レスポンスが返されます。
Geolocation のレスポンス
位置情報リクエストが成功すると、位置と半径を定義する JSON 形式のレスポンスが返されます。
location
: ユーザーが推定した緯度と経度の座標(度単位)。1 つのlat
と 1 つのlng
サブフィールドが含まれます。accuracy
: 推定される位置情報の精度(メートル単位)。指定されたlocation
を中心とする円の半径を表します。
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }