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

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 WiFi と基地局の信号がない場合、空の場合、またはデバイスの位置を推定するには不十分な場合に、フォールバックして 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 配列には、ゼロ個以上の携帯電話の基地局オブジェクトを含めます。

フィールド 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 ～ 65,535。
nr を使用した場合の有効範囲: 0 ～ 16777215。
mobileCountryCode number（uint32） 携帯電話の基地局のモバイル カントリーコード（MCC）です。 radioType gsm（デフォルト）、wcdma、lte、nr では必須です。cdma では使用されません。
有効な範囲: 0 ～ 999。
mobileNetworkCode number（uint32） 携帯電話の基地局のモバイル ネットワーク コード（MNC）です。 これは、GSM、WCDMA、LTE、NR の MNC です。
CDMA では System 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 ビットの Cell ID（CID）をそのまま使用します。有効な範囲は 0 ～ 65535 です。
  • CDMA（2G）ネットワークでは、16 ビットの基地局 ID（BID）がそのまま使用されます。有効な範囲は 0 ～ 65,535 です。
  • WCDMA（3G）ネットワークでは、UTRAN/GERAN セル ID（UC-ID）が使用されます。これは、12 ビットの無線ネットワーク コントローラ ID（RNC-ID）と 16 ビットのセル ID（CID）を連結した 28 ビットの整数値です。
    数式: rnc_id << 16 | cid。
    有効な範囲: 0 ～ 268435455。
    注: WCDMA ネットワークで 16 ビットの Cell ID の値のみを指定すると、正しくない結果またはゼロの結果が返されます。
  • LTE（4G）ネットワークでは、E-UTRAN セル ID（ECI）が使用されます。これは、20 ビットの E-UTRAN ノード B ID（eNBId）と 8 ビットのセル 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 つ以上の WiFi アクセス ポイント オブジェクトを含める必要があります。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": "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 への入力から削除する必要があります。

たとえば、位置情報に使用できる 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: ユーザーの推定の緯度と経度の座標（度単位）。lat サブフィールドと lng サブフィールドが 1 つずつ含まれます。
  • accuracy: 推定位置の精度（メートル単位）。これは、指定された location を中心とした円の半径です。
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}