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

Geolocation リクエスト

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

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

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

リクエストの本文

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

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 配列には、ゼロ個以上の 携帯電話の基地局オブジェクトが含まれます。

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

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 ビットの無線ネットワーク コントローラ ID（RNC-ID）と 16 ビットのセル ID（CID）を連結した 28 ビットの整数値 です。
  数式: rnc_id << 16 | cid。
  有効範囲: 0 ～ 268435455。
  注: WCDMA ネットワークで 16 ビットのセル 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 ビットのセル ID 値のみを指定すると、 誤った結果またはゼロの結果が返されます。

API リクエストでこれらの範囲外の値を指定すると、動作が未定義になる可能性があります。 Google の裁量により、API は数値を切り捨ててドキュメントに記載されている範囲に収まるようにしたり、 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` の計算 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 つ以上の WiFi アクセス ポイント オブジェクトを含める必要があります。macAddress フィールドは 必須です。それ以外のフィールドはすべて省略可能です。 このサービスでは、飛行機や電車など、移動するアクセス ポイント は無視されます。

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

{
  ...
  
  "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
}

サンプル リクエスト

サンプルデータで 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
}

未使用の WiFi アクセス ポイントの削除

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

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

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

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")));
    

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')]
    

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 つ未満の WiFi MAC アドレスが含まれているため、 リクエストは成功せず、HTTP 404 （notFound） レスポンスが返されます。

Geolocation のレスポンス

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 の範囲です。
• 携帯電話の基地局: WiFi 情報が利用できない場合や不十分な場合、 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 Geolocation: considerIp が true で、WiFi 信号または携帯電話の基地局信号をジオロケーションできない場合、API はリクエストの IP アドレスに基づいて位置を推定します。この方法では、精度が最も低く、半径が数千メートルになることがあります。トラブルシューティング ガイドの精度範囲が非常に大きいのはなぜですか？をご覧ください。