[5] Geolocation オブジェクトのメソッドで位置情報を取得できます。

仕様書

引数

[110] getCurrentLocation メソッドと watchPosition メソッドの第3引数は、 PositionOptions 辞書を指定できます。 省略可能で、既定値は空の辞書です。

[111] PositionOptions は、 3つの辞書メンバーのある辞書です。 >>3

[112] PositionOptions 辞書メンバー

処理

[6] Geolocation インターフェイスの getCurrentLocation メソッドは、 次のようにしなければなりません。 >>3

  1. [7] 成功コールバックを、 必須の第1引数を PositionCallback と解釈した結果に設定します。
  2. [8] エラーコールバックを、 第2引数を PositionErrorCallback と解釈した結果に設定します。
  3. [9] オプション群を、 第3引数を PositionOptions と解釈した結果に設定します。
  4. [90] 設定群を、 環境設定群オブジェクトに設定します。

[10] 更に、 成功コールバック、 エラーコールバック、 オプション群、 設定群について、 非同期的に次のようにしなければなりません。 >>3

  1. [92] 許可を確認します (>>91)。
    エラーコールバック
    エラーコールバック
    設定群
    設定群
    次の処理
    >>93

[93] 次の処理は、次のようにします。 >>3

  1. [11] 位置を、 キャッシュされた GeolocationPosition に設定します。
  2. [23] 位置の齢がオプション群の maxAge 以下の場合、
    1. [24] 成功コールバックに位置を報告し、ここで停止します。
  3. [15] オプション群の timeoutPositionOptions が 0 の場合、
    1. [26] エラーを、 新しい GeolocationPositionError に設定します。
      GeolocationPositionError
      codeGeolocationPositionError
      TIMEOUTGeolocationPositionError
    2. [21] エラーコールバックにエラーを報告し、ここで停止します。
  4. [70] 中断信号を、未中断に設定します。
  5. [81] 成功コールバック、 エラーコールバック、 オプション群、 中断信号について、 取得の手順群 (>>82) を実行します。

[42] Geolocation インターフェイスの watchPosition メソッドは、 次のようにしなければなりません。 >>3

  1. [43] 成功コールバックを、 必須の第1引数を PositionCallback と解釈した結果に設定します。
  2. [44] エラーコールバックを、 第2引数を PositionErrorCallback と解釈した結果に設定します。
  3. [45] オプション群を、 第3引数を PositionOptions と解釈した結果に設定します。
  4. [97] ハンドルの状態を、 文脈オブジェクトのハンドルハンドル (JavaScript)の状態に設定します。
  5. [52] 識別子を、 ハンドルの状態における新しいハンドルハンドル (JavaScript)に設定します。
  6. [94] 設定群を、 環境設定群オブジェクトに設定します。
  7. [53] 識別子を返します。

[46] 更に、 成功コールバック、 エラーコールバック、 オプション群、 ハンドルの状態、 識別子、 設定群について、 非同期的に次のようにしなければなりません。 >>3

  1. [47] 許可を確認します (>>91)。
    エラーコールバック
    エラーコールバック
    設定群
    設定群
    次の処理
    1. [51] 成功コールバック、 失敗コールバック、 オプション群、 ハンドルの状態、 識別子について watch process を実行します。

[58] 成功コールバック、 失敗コールバック、 オプション群、 ハンドルの状態、 識別子について watch process は、 次のようにします。 >>3

  1. [95] ハンドルの状態において識別子の中断信号が中断済みの場合、
    1. [96] ここで停止します。
  2. [36] 以前の位置を、 null に設定します。
  3. [59] 位置を、 キャッシュされた GeolocationPosition に設定します。
  4. [60] 位置の齢がオプション群の maxAge 以下の場合、
    1. [62] 成功コールバックに位置を報告します。
    2. [35] 以前の位置を、位置に設定します。
  5. [61] 成功コールバック、 エラーコールバック、 オプション群、 ハンドルの状態、 識別子、 以前の位置について、 acquisition steps を実行します。

[63] 成功コールバック、 エラーコールバック、 オプション群、 ハンドルの状態、 識別子、 以前の位置について acquisition steps は、 次のようにします。 >>3

  1. [98] ハンドルの状態において識別子についての中断信号が中断済みの場合、
    1. [99] ここで停止します。
  2. [34] 取得の手順群 (>>82) を実行します。
    成功コールバック
    成功コールバック、
    エラーコールバック
    エラーコールバック
    オプション群
    オプション群
    以前の位置
    以前の位置
    watch
    真
    中断信号
    ハンドルの状態における識別子についての中断信号。
    次の処理
    1. [85] 実装依存の時間、待ちます。
    2. [84] 成功コールバック、 エラーコールバック、 オプション群、 ハンドルの状態、 識別子、 以前の位置について acquisition steps を実行します。

[91] 許可を確認するには、 エラーコールバック、 設定群、 次の処理について、 次のようにします。 >>3

  1. [17] 設定群の非保安文脈が真の場合、
    1. [18] エラーを、 新しい GeolocationPositionError に設定します。
      GeolocationPositionError
      codeGeolocationPositionError
      PERMISSION_DENIEDGeolocationPositionError
    2. [19] 開発者コンソールにエラーを表示して構いません。
    3. [20] エラーコールバックにエラーを報告し、ここで停止します。
  2. [48] 利用者の許可を照会しますPermission。
    許可の存在を確認できたときの処理
    次の処理
    不許可の存在を確認できたときの処理
    1. [49] エラーを、 新しい GeolocationPositionError に設定します。
      GeolocationPositionError
      codeGeolocationPositionError
      PERMISSION_DENIEDGeolocationPositionError
    2. [50] エラーコールバックにエラーを報告します。

測位

[117] 現在 Web が利用されている一般的な機器には GPS などによる位置情報取得のための装置が組み込まれています。 Webブラウザーが動作するプラットフォーム (OS やライブラリー) には、 こうした装置を通じて位置情報を取得する機能が用意されています。 getCurrentPosition や watchPosition は究極的にはこれを呼び出すことになります。

[131] 経緯度の他に、 高度、 移動の速度と方向が取得できることになっています。 ただし必須なのは経緯度だけです。 それ以外も取得できるのかはプラットフォーム (と接続されているセンサー) 次第です。

[134] Webブラウザーによっては、 開発者たる利用者が位置情報を任意に設定開発モードできます。

[82] 成功コールバック、 エラーコールバック、 オプション群、 以前の位置、 watch (既定値は偽)、 中断信号、 次の処理 (既定値は何もしない) について取得の手順群は、 次のようにします。 >>3

  1. [28] タイマーを、新しいタイマーを作成した結果に設定します。
    時間
    オプション群の timeoutPositionOptions ミリ秒
    時間経過後非同期的に実行する処理
    1. [32] タイマーの停止済みが真の場合、
      1. [33] ここで停止します。
    2. [69] 中断信号を、中断済みに設定します。
    3. [29] エラーを、 新しい GeolocationPositionError に設定します。
      GeolocationPositionError
      codeGeolocationPositionError
      TIMEOUTGeolocationPositionError
    4. [30] エラーコールバックにエラーを報告します。
    5. [65] 次の処理を実行します。
  2. [27] プラットフォームから位置情報を取得します。
    取得方法決定のヒント
    オプション群の enableHighAccuracy
    取得成功時に非同期的に実行する処理
    1. [31] 中断信号が中断済みの場合、
      1. [78] ここで停止します。
    2. [72] タイマーの停止済みを真に設定します。
    3. [79] 位置を、 新しい GeolocationPosition に設定します。
    4. [74] キャッシュされた GeolocationPosition を、 位置に設定します。
    5. [39] watch が真で、 実装依存の基準でコールバックが呼ばれすぎていると判断される場合、
      1. [66] 次の処理を実行します。
      2. [40] ここで停止します。
    6. [75] 成功コールバックに以前の位置について位置を報告します。
    取得失敗時に非同期的に実行する処理
    1. [76] 中断信号が中断済みの場合、
      1. [73] ここで停止します。
    2. [77] タイマーの停止済みを真に設定します。
    3. [41] watch が真で、 実装依存の基準でコールバックが呼ばれすぎていると判断される場合、
      1. [83] 次の処理を実行します。
      2. [64] ここで停止します。
    4. [80] エラーを、 新しい GeolocationPositionError に設定します。
      GeolocationPositionError
      codeGeolocationPositionError
      POSITION_UNAVAILABLE
    5. [71] エラーコールバックにエラーを報告します。
    6. [67] 次の処理を実行します。
    取得を中断する条件
    中断信号が中断済みになったとき

取得装置

[123] プラットフォームは複数の測位手段に対応していることがあります。 GPS による位置情報の取得の他に、 WiFi 情報などを利用した位置の推定技法が使われることがあります。 その他屋内での位置決定用のビーコン利用など、 いろいろな手法が考えられ、 プラットフォーム、 装置、 利用環境その他によって得られる精度、電力消費、必要時間などが異なります。 Geolocation API はそうした測位手法の詳細を指定する手段を Webアプリケーションに提供せず、 むしろ抽象化し意識せずに利用できるようにしていますが、 唯一、高精度な位置情報を望むか否かだけ、 指定できるようになっています。

[118] getCurrentPosition メソッドや watchPosition メソッドの第3引数の PositionOptions 辞書には、 enableHighAccuracy 属性を指定できます。

[119] PositionOptions 辞書の enableHighAccuracy 属性は、 応用が出来得る最善の結果の受信を希望するとのヒントを示すものです。 高精度な位置情報が不要な応用がこれを示すことで実装の消費電力を削減することが想定されています。 値は boolean で、 省略時の既定値は false です。 >>3

[120] この属性が指定された場合、 応答時間が長くなったり、 電力消費が大きくなったりするかもしれません。 >>3

[122] 装置によっては「より正確な結果」を提供し得ないかもしれません >>3。 そのときエラーを返すべきなのか、 偽が指定されたのと同じ挙動をするべきなのか不明です。 ヒントでもありますし、一般には後者の方が便利そうです。

[121] 利用者はこの能力の利用を拒絶するかもしれません >>3。 そのときエラーを返すべきなのか、 偽が指定されたのと同じ挙動をするべきなのか不明です。 ヒントでもありますし、一般には後者の方が便利そうです。 このような選択肢を提供する実装があるのか不明です。

タイムアウト

[124] PositionOptions 辞書の timeoutPositionOptions 属性は、 コールバック関数を呼び出すまでの時間の長さの最大値を指定するものです。 値は unsigned long に Clamp されるものであって、 省略時の既定値は 0xFFFFFFFF です。 ミリ秒単位の時間長と解されます。 >>3

[125] この時間は、位置情報の取得のみにかかります >>3。 利用者の許可の取得Permissionの時間は含まれません。

キャッシュ

[109] getCurrentPosition と watchPosition のコールバック関数に与えられる GeolocationPosition は、 キャッシュできることになっています。 つまり前に得たのと同じオブジェクトが得られる場合があります。

[22] キャッシュの利用可能範囲は仕様書に明記がありません。 現在の文書でしょうか。 getCurrentPosition と watchPosition で共有できるのかも定かではありません。 同じ watchPosition の実行では何度も同じコールバック関数が同じオブジェクトで呼び出されることはないような規定となっており、 同時に実行される他の watchPosition とも共用されないような規定になっています。 こうした細かな挙動が本当に意図通りなのか、そしてそのように実装されているのかは、 よくわかりません。

[86] 仕様書は GeolocationPosition の再利用のみ想定していて、 別の文書が取得した情報やほかのアプリの取得した情報の (プラットフォームを介した) 再利用は規定していません。 Webブラウザーやプラットフォームの設計によりそうした再利用が発生することも考えられます。 もちろんその場合は測位値は再利用でも GeolocationPosition オブジェクトは新しいものになります。 (そしてそのような形の再利用は仕様違反ではありません。)

[126] PositionOptions 辞書の maximumAge 属性は、 応用が受け入れられる、キャッシュされた位置の齢の最大値です。 値は Clamp される unsigned long で、省略時の既定値は 0 です。 ミリ秒単位の時間長です。 >>3

[127] watchPosition では、 最初の位置情報に適用されます >>3。

[130] キャッシュされた位置の齢が指定された値より小さいなら、 それを返します。そうでない場合、 新しい位置情報を取得しようと試みなければなりません。 >>3

[128] 値が 0 のとき、キャッシュされた位置は使わず、 ただちに新しい位置情報を取得しようと試みなければなりません。 >>3

[129] 値が Infinity のとき、 齢に関わらずキャッシュされた位置情報を返さなければなりません。 >>3 (と仕様書にはありますが、 Clamped unsigned long なので、 Infinity が指定されると 0xFFFFFFFF と解されます。 これは49日余に相当します。)

コールバック関数

[115] getCurrentPosition、 watchPosition とも、 第1引数には取得成功時のコールバック関数 (必須)、 第2引数には取得失敗時のコールバック関数 (省略可能) を指定できます。

[116] コールバック関数は、取得後に非同期的に呼び出されます。

[54] PositionCallback は、 コールバック関数で、 GeolocationPosition を引数として実行されます。 返り値は使われません。 >>3

[56] getCurrentLocation メソッドと watchPosition メソッドの第1引数として指定でき、必須です。 getCurrentLocation では高々1回呼び出されます。 watchPosition では任意の回数呼び出されます。

[13] 成功コールバックに省略可能な以前の位置について GeolocationPosition 位置を報告するには、 次のようにします。 >>3

  1. [37] 以前の位置が null でなく、 実装依存の基準により以前の位置と位置が十分異なるnew position differs significantly from the previous positionといえないと判断される場合、
    1. [38] ここで停止します。
  2. [12] 位置について、 成功コールバックを呼び出しコールバックの実行ます。

[87] watchPosition のコールバック関数の呼び出しについて、 仕様書上は値が変化したときとされていて、 値が十分に変化したと認められない時通知されないように規定されています。 さらに、 ネットワークの変化など位置が変化した可能性があると判断し得るときに測位することになっています。 逆に変化した場合であってもコールバック関数の呼び出しは適宜間引いて良いことにされています。

[88] 性質上、こうした規定が忠実に実装されているか確認することは困難です。

[89] 実際に試してみると、値が変化していなくてもコールバック関数が一定時間ごとに呼び出されることがあるようです。

[133] コールバック関数の処理内容や実行環境の性能上の制限によっては、 高頻度でコールバック関数が呼び出されることで正常な動作に支障が生じる場合があります。 そのためWebブラウザーはコールバック関数の呼び出し頻度を抑えることが認められています。

[132] 一般的な実装ではせいぜい秒単位の頻度でしか呼び出されません。 非常に高頻度で呼び出されるとセキュリティー上の問題が生じる危険性もあります。 DOMHighResTimeStamp

[55] PositionErrorCallback は、 コールバック関数で、 GeolocationPositionError を引数として実行されます。 返り値は使われません。 >>3

[57] getCurrentLocation メソッドと watchPosition メソッドの第2引数として指定できますが、 省略可能です。 省略された場合エラーは捨てられます。 getCurrentPosition メソッドでは高々1回呼び出されます。

[25] エラーコールバックに GeolocationPositionError エラーを報告するには、 次のようにします。 >>3

  1. [14] エラーコールバックが指定された場合、
    1. [16] エラーについて、 エラーコールバックを呼び出しコールバックの実行ます。

[68] コールバック関数内の例外の処理は、仕様書上明確になっていません。 例外の報告がなされて処理が継続されるものとみられます。

ハンドル

[113] watchPosition メソッドはハンドルハンドル (JavaScript)を返します。 clearWatch メソッドにこのハンドルハンドル (JavaScript)を渡すことで、 watch を停止できます。

[114] setTimeout / setInterval はどちらもハンドルハンドル (JavaScript)を返し、 どちらも停止できます。 getCurrentPosition / watchPosition はそれと対になるものですが、 getCurrentPosition はハンドルハンドル (JavaScript)を返さないので中断できません。

[100] Geolocation インターフェイスの clearWatch メソッドは、 次のようにしなければなりません。 >>3

  1. [101] 識別子を、 必須の第1引数を long と解釈した結果に設定します。
  2. [102] ハンドルの状態を、 文脈オブジェクトのハンドルハンドル (JavaScript)の状態に設定します。
  3. [103] ハンドルの状態において識別子が未使用の場合、
    1. [104] ここで停止します。
  4. [105] ハンドルの状態における識別子の中断信号を、中断済みに設定します。

セキュリティーとプライバシー

[107] 位置情報の取得は、 利用者の同意が必要となっています。 Permission

[108] 位置情報の受信者は、 これが必要な時だけ要求するようにしなければなりません。 受信者は、位置情報を取得した目的にのみこれを用いなければならず、 利用者が保持し続けることを認めた場合を除き、完了したら破棄しなければなりません。 受信者は、位置情報への無許可のアクセスを認めないように対策しなければなりません。 位置情報が蓄積される場合には、利用者がこれを更新・削除できるべきです。 利用者が認めた場合を除き、位置情報を再転送してはなりません。 再転送する場合には注意を払うべきで、 暗号化することをおすすめしますencouraged。 受信者は、 位置情報を収集していること、その目的、保存期間、安全対策、 共有する場合どう共有されるか、利用者がどうアクセス、更新、削除できるか、 その他利用者が行えることを明確に開示しなければなりません。 以上の指針に従わない場合には、その説明も開示しなければなりません。 >>106

歴史

[1] Geolocation API Specification ( ( 版)) http://www.w3.org/TR/geolocation-API/#get-current-position

[4] Geolocation API Specification () https://w3c.github.io/geolocation-api/#dom-geolocation-watchposition

[2] Android の Chrome では、既定の状態で、ほぼ毎秒くらいの頻度でコールバックが呼び出されます。