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

Geolocation リクエスト

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

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

リクエストにはキーを指定する必要があります。キーは key パラメータ。key は、アプリケーションの API キー。このキーを使ってアプリケーションを識別し、割り当て量を管理します。キーの取得方法を確認する。

リクエスト本文

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

フィールド JSON 型 説明 メモ
homeMobileCountryCode numberuint32 デバイスのホーム ネットワークのモバイル カントリー コード(MCC)。 radioType gsm(デフォルト)で対応wcdmaltenrcdma では使用されません。
有効範囲: 0 ~ 999。
homeMobileNetworkCode numberuint32 デバイスのホーム ネットワークのモバイル ネットワーク コード。 GSM、WCDMA、LTE、NR 向けの MNC です。
CDMA はシステム ID(SID)を使用します
MNC の有効範囲: 0 ~ 999。
SID の有効範囲は 0 ~ 32767 です。
radioType string モバイル無線タイプ。サポートされている値は gsmcdmawcdmaltenr このフィールドは省略可能ですが、ラジオボタンの種類が 認識できます。
フィールドを省略すると、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 numberuint32 セルの一意の識別子です。 必須: radioTypegsm(デフォルト)、cdmawcdmaltenr については不承認となります。
以下の cellId の計算セクションをご覧ください。こちらのセクションには、 各無線タイプの有効な値の範囲。
newRadioCellId numberuint64 NR(5G)セルの一意の識別子。 radioType nr の場合は必須です。不承認(その他) できます。
以下の NewRadioCellId の計算セクションをご覧ください。 フィールドの有効な値の範囲もリストされます。
locationAreaCode numberuint32 GSM ネットワークと WCDMA ネットワークの地域コード(LAC)。
CDMA ネットワークのネットワーク ID(NID)。
LTE ネットワークと NR ネットワークのトラッキング市外局番(TAC)。
必須: radioType gsm(デフォルト)と cdma(他の値では省略可)。
有効範囲: gsmcdmawcdmalte: 0 ~ 65535。
nr を使用した場合の有効範囲: 0~16777215。
mobileCountryCode numberuint32 基地局のモバイル カントリー コード(MCC)。 必須: radioTypegsm(デフォルト)、wcdmaltenrcdma では使用されません。
有効範囲: 0 ~ 999。
mobileNetworkCode numberuint32 基地局のモバイル ネットワーク コード。 GSM、WCDMA、LTE、NR 向けの MNC です。
CDMA はシステム ID(SID)を使用します。
必須。
MNC の有効範囲: 0 ~ 999。
SID の有効範囲は 0 ~ 32767 です。

次のオプション フィールドは使用されていませんが、値が一致している場合に できます。

フィールド JSON 型 説明 メモ
age numberuint32 このセルがプライマリであったときからの経過時間(ミリ秒)です。 年齢が 0 の場合、cellId または newRadioCellId は現在の 測定します
signalStrength numberdouble dBm 単位の無線通信の信号強度です。
timingAdvance numberdouble タイミング アドバンス あります。

cellId を計算しています

NR(5G)より前の無線タイプでは、ネットワークを渡すために 32 ビットの cellId フィールドを使用します。 セル ID を Geolocation API に渡します。

  • GSM(2G)ネットワークは、16 ビットの Cell ID(CID)をそのまま使用します。有効範囲: 0 ~ 65535。
  • CDMA(2G)ネットワークは、16 ビットのベースステーション ID(BID)をそのまま使用します。有効範囲: 0 ~ 65535。
  • WCDMA(3G)ネットワークは UTRAN/GERAN Cell Identity(UC-ID)を使用します。これは 28 ビットの整数 12 ビットの無線ネットワーク コントローラ識別子(RNC-ID)と 16 ビットを連結した値 セル ID(CID)。
    数式: rnc_id << 16 | cid
    有効範囲: 0 ~ 268435455。
    注: WCDMA ネットワークで 16 ビットの Cell ID 値のみを指定すると、 正しくない、またはまったくないという状況です。
  • LTE(4G)ネットワークは E-UTRAN Cell Identity(ECI)を使用します。ECI は 28 ビットの整数値です。 20 ビットの E-UTRAN ノード B 識別子(eNBId)と 8 ビットのセル ID(CID)を連結する。
    数式: 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 ビット ネットワーク セル ID を渡すための newRadioCellId フィールド 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 は必須です。すべて 他のフィールドは省略可能です。

フィールド JSON 型 説明 メモ
macAddress string Wi-Fi ノードの MAC アドレス。通常は、BSS、BSSID、または MAC アドレスと呼ばれます。 必須。コロンで区切られた(:)16 進数文字列。
限定 普遍的に管理される MAC アドレスは API で確認できます。その他の MAC アドレスは 通知なく破棄され、その結果、API リクエストが実質的に 空です。詳しくは、不要な Wi-Fi アクセスの切断をご覧ください。 。
signalStrength numberdouble dBm で計測した現在の信号強度です。 Wi-Fi アクセス ポイントの場合、dBm 値は通常 -35 以下で、-128~-10 dBm の範囲です。 必ずマイナス記号を含めてください。
age numberuint32 このアクセス ポイントが検出されてからの経過時間(ミリ秒)です。
channel numberuint32 クライアントがアクセス ポイントとの通信を行っているチャネルです。
signalToNoiseRatio numberdouble 現在の信号雑音比 単位は 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 アドレスは、ユーザーの位置情報には有効ではありません。 通知なくリクエストからドロップされます。このような MAC アドレスは削除できます。 データの 2 番目に下位のビットが macAddress の最上位バイトは 0 です。たとえば、 2 で表される 1 ビットを 02:00:00:00:00:00。ブロードキャスト MAC アドレス (FF:FF:FF:FF:FF:FF)は MAC アドレスの例です。 このフィルタで効果的に除外できます。

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

たとえば、位置情報で使用可能な MAC アドレスは、 macs という名前の macAddress 文字列の配列:

<ph type="x-smartling-placeholder">
</ph>
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")));
    
をご覧ください。 <ph type="x-smartling-placeholder">
</ph>
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')]
    
をご覧ください。 <ph type="x-smartling-placeholder">
</ph>
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
}