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

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 ネットワーク用の 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）より前の無線タイプでは、ネットワーク セル ID を Geolocation API に渡すために 32 ビット cellId フィールドを使用します。

  • GSM（2G）ネットワークは、16 ビットの Cell ID（CID）をそのまま使用します。有効範囲は 0 ～ 65535 です。
  • CDMA（2G）ネットワークは、16 ビットの Base Station ID（BID）をそのまま使用します。有効範囲: 0 ～ 65535。
  • WCDMA（3G）ネットワークは、UTRAN/GERAN Cell Identity（UC-ID）を使用します。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）を使用します。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 ビットを超える新しいネットワークでは、ネットワーク セル ID を Geolocation API に渡すために 64 ビットの newRadioCellId フィールドを使用します。

  • 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 です。 必ずマイナス記号を含めてください。
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 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
}

使用していない 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 文字列の配列から収集できます。

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 のみがリストに残ります。このリストにある 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
}