位置情報のリクエストとレスポンス

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 アクセス ポイント オブジェクトの配列です。 下記の WiFi アクセス ポイント オブジェクトのセクションをご覧ください。

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 ネットワークの Location Area Code（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 ビットのセル ID（CID）をそのまま使用します。有効な範囲: 0 ～ 65535。
  • CDMA（2G）ネットワークは 16 ビットの基地局 ID（BID）をそのまま使用します。有効な範囲は 0 ～ 65535 です。
  • WCDMA（3G）ネットワークは、12 ビットの無線ネットワーク コントローラ識別子（RNC-ID）と 16 ビットのセル ID（CID）を連結した 28 ビットの整数値である UTRAN/GERAN セル ID（UC-ID）を使用します。
    数式: rnc_id << 16 | cid。
    有効な範囲: 0 ～ 268435455。
    注: WCDMA ネットワークで 16 ビットのセル ID 値のみを指定すると、結果が正しくないかゼロになります。
  • LTE（4G）ネットワークは、20 ビットの E-UTRAN Node B 識別子（eNBId）と 8 ビットのセル ID（CID）を連結した 28 ビットの整数値である E-UTRAN Cell Identity（ECI）を使用します。
    数式: 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 進数文字列。
API を介して特定できるのは、ユニバーサル管理の MAC アドレスのみです。他の MAC アドレスは暗黙的にドロップされ、API リクエストが事実上空になる可能性があります。詳しくは、不要な Wi-Fi アクセス ポイントを削除するをご覧ください。
signalStrength number（double） dBm で計測した現在の信号強度です。 Wi-Fi アクセス ポイントの場合、dBm 値は通常 -35 以下で、-128 ～-10 dBm の範囲です。マイナス記号を必ず含めてください。
値が -10 dBm より大きい場合、API は NOT FOUND を返します。
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 用に予約されており、ネットワーク管理やマルチキャスト機能によく使用されるため、位置情報シグナルとして使用することはできません。また、これらの MAC アドレスを API の入力から削除する必要があります。

たとえば、Geolocation で使用可能な MAC アドレスは、macs という名前の macAddress 文字列の配列から収集できます。

Java
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")));
Python
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')]
JavaScript
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 のみが残ります。このリストには 2 つ未満の Wi-Fi MAC アドレスが含まれているため、リクエストは成功せず、HTTP 404 （notFound）レスポンスが返されます。

Geolocation のレスポンス

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

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