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

Geolocation リクエスト

Geolocation リクエストは、次の URL に POST で送信します。

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

リクエストでキーを指定する必要があります。キーは key パラメータの値として含まれます。key はアプリケーションの API キーです。このキーは、割り当て管理の目的でアプリケーションを識別します。キーを取得する方法を学ぶ。

リクエストの本文

リクエストの本文は JSON 形式でなければなりません。リクエストの本文が含まれていない場合、リクエストの場所の IP アドレスに基づいて結果が返されます。次のフィールドがサポートされています。特に記載がない限り、すべてのフィールドは省略可能です。

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 個以上の携帯基地局オブジェクトが含まれます。

次の省略可能なフィールドは使用されませんが、値が利用可能な場合は含めることができます。

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 セル ID（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 は必須です。他のフィールドはすべて省略可能です。

次に、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 文字列の配列から収集できます。

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