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

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": "lte",
  "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）	このセルがプライマリであったときからの経過時間（ミリ秒）です。	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 ビットの基地局 ID（BID）をそのまま使用します。有効な範囲は 0 ～ 65535 です。
• WCDMA（3G）ネットワークでは、UTRAN/GERAN セル ID（UC-ID）が使用されます。これは、12 ビットの無線ネットワーク コントローラ識別子（RNC-ID）と 16 ビットのセル ID（CID）を連結した 28 ビットの整数値です。
  計算方法: rnc_id << 16 | cid。
  有効範囲: 0 ～ 268435455。
  注: WCDMA ネットワークで 16 ビットのセル ID 値のみを指定すると、結果が不正確になるか、ゼロになります。
• LTE（4G）ネットワークでは、E-UTRAN Cell Identity（ECI）を使用します。これは、20 ビットの E-UTRAN Node B Identifier（eNBId）と 8 ビットの Cell 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
    }
  ]
}

上記のリクエストに対するレスポンスは次のようになります。

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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,
    }
  ]
}

上記のリクエストに対するレスポンスは次のようになります。

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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 単位）。

リクエスト本文の一部である Wi-Fi アクセス ポイント オブジェクトの例を以下に示します。

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

上記のリクエストに対するレスポンスは次のようになります。

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

サンプル リクエスト

注: MAC アドレスは時間の経過とともに変更される可能性があります。そのため、このページに記載されている例では、API からエラー メッセージが返されることがあります。

サンプルデータを使用して 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 がブロードキャスト アドレス（FF:FF:FF:FF:FF:FF）または IANA によって予約されている Wi-Fi アクセス ポイント オブジェクトを削除すると、Wi-Fi を入力として使用する Geolocation API 呼び出しの成功率が向上します。フィルタリング後に Geolocation API 呼び出しが成功しないと判断された場合は、古い位置情報シグナルや、シグナルの弱い Wi-Fi AP を使用するなどの緩和策を使用できます。このアプローチは、アプリケーションの位置情報の推定の必要性と、適合率と再現率の要件とのトレードオフになります。次のフィルタリング手法は、入力をフィルタする方法を示していますが、アプリケーション エンジニアが適用することを選択できる緩和策は示していません。

00:00:5E:00:00:00 から 00:00:5E:FF:FF:FF までの MAC アドレスの範囲は IANA 用に予約されており、ネットワーク管理やマルチキャスト機能によく使用されるため、位置情報シグナルとして使用することはできません。また、これらの MAC アドレスを API への入力から削除する必要があります。

たとえば、位置情報に使用できる MAC アドレスは、macs という名前の macAddress 文字列の配列から収集できます。

Java

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

Python

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

JavaScript

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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
}

この API は、入力シグナルに基づいて位置情報と精度範囲を返します。この API は高精度の位置情報を返すことができますが、精度は利用可能な信号のソース、数、密度、強度によって異なる場合があります。通常、次の精度半径が想定されます。

• Wi-Fi アクセス ポイント: リクエストに 2 つ以上の wifiAccessPoints が含まれている場合、返される精度の半径は通常 20 メートル前後です。アクセス ポイントの数が増え、信号が強くなる（dBm 単位で測定）ほど、精度が向上します。信号強度は通常、-100 ～-20 dBm の範囲です。
• 基地局: Wi-Fi 情報が利用できないか不十分な場合、API は cellTowers を使用して位置情報を取得します。精度は、基地局の種類、信号強度、ネットワーク密度によって大きく異なります。
  • マクロセル（最も一般的なタイプで、広域をカバーするために使用される）は、精度が低くなります。半径は通常、数百メートルの範囲ですが、携帯電話基地局のカバー範囲が狭い地域では数千メートルになることもあります。マクロセルの場合、精度半径が 100 メートル未満になることはまれです。一般に、電波の強い基地局ほど精度が高くなります。通常、強い信号は、LTE の場合は -110 dBm 超（信号範囲 -140 ～-55 dBm）、WCDMA の場合は -100 dBm 超（信号範囲 -111 ～-53 dBm）、CDMA の場合は -100 dBm 超（信号範囲 -120 ～-40 dBm）、GSM の場合は -80 dBm 超（信号範囲 -121 ～-1 dBm）です。
  • スモールセル（フェムトセル、ピコセル、屋内リピーターなど）は、最も精度の高いセルベースの位置情報を提供し、精度半径は 10 ～ 30 メートルの範囲になります。
• IP 位置情報: considerIp が true で、Wi-Fi または基地局の信号を位置情報に変換できない場合、API はリクエストの IP アドレスに基づいて位置情報を推定します。この方法では精度が最も低く、半径が数千メートルになることもあります。精度半径が非常に大きいのはなぜですか？をご覧ください。トラブルシューティング ガイドを参照してください。