forked from w3c/geolocation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
1158 lines (1140 loc) · 50.4 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>
Geolocation API Specification
</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" async class=
"remove"></script>
<script class="remove">
var respecConfig = {
shortName: "geolocation-API",
mdn: "geolocation-api",
specStatus: "ED",
editors: [
{
name: "Devices and Sensors Working Group",
},
],
formerEditors: [
{
name: "Andrei Popescu",
company: "Google Inc.",
companyURL: "https://google.com/",
w3cid: "36565",
},
],
group: "das",
previousPublishDate: "2016-11-08",
previousMaturity: "REC",
github: "w3c/geolocation-api",
caniuse: "geolocation",
testSuiteURI: "https://web-platform-tests.live/geolocation-API/",
// implementationReportURI: "https://wpt.fyi/geolocation-API",
localBiblio: {
WGS84: {
title:
"National Imagery and Mapping Agency Technical Report 8350.2, Third Edition",
href:
"http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf",
publisher: "National Imagery and Mapping Agency",
date: "3 January 2000",
},
AZALOC: {
href:
"http://www.azarask.in/blog/post/geolocation-in-firefox-and-beyond/",
title: "Geolocation in Firefox and Beyond",
authors: ["Aza Raskin"],
},
},
xref: "web-platform",
};
</script>
</head>
<body data-cite="secure-contexts permissions-policy">
<section id="abstract">
<p>
This specification defines an API that provides scripted access to
geographical location information associated with the hosting device.
</p>
</section>
<section id="sotd">
<p>
The Devices and Sensors Working Group will maintain errata and new
editions, as necessary, for the Geolocation API.
</p>
</section>
<section id="introduction" class="informative">
<h2>
Introduction
</h2>
<p>
The Geolocation API defines a high-level interface to location
information associated only with the device hosting the implementation,
such as latitude and longitude. The API itself is agnostic of the
underlying location information sources. Common sources of location
information include Global Positioning System (GPS) and location
inferred from network signals such as IP address, RFID, WiFi and
Bluetooth MAC addresses, and GSM/CDMA cell IDs, as well as user input.
No guarantee is given that the API returns the device's actual
location.
</p>
<p>
The API is designed to enable both "one-shot" position requests and
repeated position updates, as well as the ability to explicitly query
the cached positions. Location information is represented by latitude
and longitude coordinates. The Geolocation API in this specification
builds upon earlier work in the industry, including [[AZALOC]], the
Gears Geolocation API, and LocationAware.org .
</p>
<p>
The following code extracts illustrate how to obtain basic location
information:
</p>
<pre class="example js" title='Example of a "one-shot" position request'>
function showMap(position) {
// Show a map centered at (position.coords.latitude, position.coords.longitude).
}
// One-shot position request.
navigator.geolocation.getCurrentPosition(showMap);
</pre>
<pre class="example js" title=
"Example of requesting repeated position updates">
function scrollMap(position) {
// Scrolls the map so that it is centered at
// (position.coords.latitude, position.coords.longitude).
}
// Request repeated updates.
var watchId = navigator.geolocation.watchPosition(scrollMap);
function buttonClickHandler() {
// Cancel the updates when the user clicks a button.
navigator.geolocation.clearWatch(watchId);
}
</pre>
<pre class="example js" title=
"Example of requesting repeated position updates and handling errors">
function scrollMap(position) {
// Scrolls the map so that it is centered at
// (position.coords.latitude, position.coords.longitude).
}
function handleError(error) {
// Update a div element with error.message.
}
// Request repeated updates.
var watchId = navigator.geolocation.watchPosition(scrollMap, handleError);
function buttonClickHandler() {
// Cancel the updates when the user clicks a button.
navigator.geolocation.clearWatch(watchId);
}
</pre>
<pre class="example js" title=
"Example of requesting a potentially cached position">
// Request a position. We accept positions whose age is not
// greater than 10 minutes. If the user agent does not have a
// fresh enough cached position object, it will automatically
// acquire a new one.
navigator.geolocation.getCurrentPosition(successCallback, errorCallback, {
maximumAge: 600000,
});
function successCallback(position) {
// By using the 'maximumAge' option above, the position
// object is guaranteed to be at most 10 minutes old.
}
function errorCallback(error) {
// Update a div element with error.message.
}
</pre>
<pre class="example js" title=
"Forcing the user agent to return a fresh cached position">
// Request a position. We only accept cached positions whose age is not
// greater than 10 minutes. If the user agent does not have a fresh
// enough cached position object, it will immediately invoke the error
// callback.
navigator.geolocation.getCurrentPosition(successCallback, errorCallback, {
maximumAge: 600000,
timeout: 0,
});
function successCallback(position) {
// By using the 'maximumAge' option above, the position
// object is guaranteed to be at most 10 minutes old.
// By using a 'timeout' of 0 milliseconds, if there is
// no suitable cached position available, the user agent
// will asynchronously invoke the error callback with code
// TIMEOUT and will not initiate a new position
// acquisition process.
}
function errorCallback(error) {
switch (error.code) {
case GeolocationPositionError.TIMEOUT:
// Quick fallback when no suitable cached position exists.
doFallback();
// Acquire a new position object.
navigator.geolocation.getCurrentPosition(successCallback, errorCallback);
break;
case ...: // treat the other error cases.
}
}
function doFallback() {
// No fresh enough cached position available.
// Fallback to a default position.
}
</pre>
<pre class="example" title=
"Forcing the user agent to return any available cached position">
// Request a position. We only accept cached positions, no matter what
// their age is. If the user agent does not have a cached position at
// all, it will immediately invoke the error callback.
navigator.geolocation.getCurrentPosition(successCallback, errorCallback, {
maximumAge: Infinity,
timeout:0
});
function successCallback(position) {
// By setting the 'maximumAge' to Infinity, the position
// object is guaranteed to be a cached one.
// By using a 'timeout' of 0 milliseconds, if there is
// no cached position available at all, the user agent
// will immediately invoke the error callback with code
// TIMEOUT and will not initiate a new position
// acquisition process.
if (position.timestamp < freshness_threshold &&
position.coords.accuracy < accuracy_threshold) {
// The position is relatively fresh and accurate.
} else {
// The position is quite old and/or inaccurate.
}
}
function errorCallback(error) {
switch(error.code) {
case GeolocationPositionError.TIMEOUT:
// Quick fallback when no cached position exists at all.
doFallback();
// Acquire a new position object.
navigator.geolocation.getCurrentPosition(successCallback, errorCallback);
break;
case ... // treat the other error cases.
};
}
function doFallback() {
// No cached position available at all.
// Fallback to a default position.
}
</pre>
</section>
<section id="scope" class="informative">
<h2>
Scope
</h2>
<p>
This specification is limited to providing a scripting API for
retrieving geographic position information associated with a hosting
device. The geographic position information is provided in terms of
World Geodetic System coordinates [[WGS84]].
</p>
<p>
The scope of this specification does not include providing a markup
language of any kind.
</p>
<p>
The scope of this specification does not include defining a new
[=url/scheme=] for building URLs that identify geographic locations.
</p>
</section>
<section id="security">
<h2>
Security and privacy considerations
</h2>
<p>
The API defined in this specification is used to retrieve the
geographic location of a hosting device. In almost all cases, this
information also discloses the location of the user of the device,
thereby potentially compromising the user's privacy. A conforming
implementation of this specification MUST provide a mechanism that
protects the user's privacy and this mechanism SHOULD ensure that no
location information is made available through this API without the
user's express permission.
</p>
<section id="privacy_for_uas">
<h3>
Privacy considerations for implementers of the Geolocation API
</h3>
<p>
User agents MUST NOT send location information to Web sites without
the express permission of the user. User agents MUST acquire
permission through a user interface, unless they have prearranged
trust relationships with users, as described below. The user
interface MUST include the {{URL/host}} component of the document's
URL. Those permissions that are acquired through the user interface
and that are preserved beyond the current browsing session (i.e.
beyond the time when the <a>browsing context</a> is navigated to
another URL) MUST be revocable and user agents MUST respect revoked
permissions.
</p>
<p>
Some user agents will have prearranged trust relationships that do
not require such user interfaces. For example, while a Web browser
will present a user interface when a Web site performs a geolocation
request, a VOIP telephone MAY NOT present any user interface when
using location information to perform an E911 function.
</p>
</section>
<section id="privacy_for_recipients">
<h3>
Privacy considerations for recipients of location information
</h3>
<p>
Recipients MUST only request location information when necessary.
Recipients MUST only use the location information for the task for
which it was provided to them. Recipients MUST dispose of location
information once that task is completed, unless expressly permitted
to retain it by the user. Recipients MUST also take measures to
protect this information against unauthorized access. If location
information is stored, users SHOULD be allowed to update and delete
this information.
</p>
<p>
The recipient of location information MUST NOT retransmit the
location information without the user’s express permission. Care
SHOULD be taken when retransmitting and use of encryption is
encouraged.
</p>
<p>
Recipients MUST clearly and conspicuously disclose the fact that they
are collecting location data, the purpose for the collection, how
long the data is retained, how the data is secured, how the data is
shared if it is shared, how users MAY access, update and delete the
data, and any other choices that users have with respect to the data.
This disclosure MUST include an explanation of any exceptions to the
guidelines listed above.
</p>
</section>
<section id="implementation_considerations" class="informative">
<h3>
Additional implementation considerations
</h3>
<p>
Further to the requirements listed in the previous section,
implementers of the Geolocation API are also advised to consider the
following aspects that MAY negatively affect the privacy of their
users: in certain cases, users MAY inadvertently grant permission to
the user agent to disclose their location to Web sites. In other
cases, the content hosted at a certain URL changes in such a way that
the previously granted location permissions no longer apply as far as
the user is concerned. Or the users might simply change their minds.
</p>
<p>
Predicting or preventing these situations is inherently difficult.
Mitigation and in-depth defensive measures are an implementation
responsibility and not prescribed by this specification. However, in
designing these measures, implementers are advised to enable user
awareness of location sharing, and to provide easy access to
interfaces that enable revocation of permissions.
</p>
</section>
</section>
<section id="api_description">
<h2>
API Description
</h2>
<section id="navigator_interface" data-dfn-for="Navigator">
<h3>
`Navigator` interface extensions
</h3>
<pre class="idl">
partial interface Navigator {
[SameObject] readonly attribute Geolocation geolocation;
};
</pre>
<section>
<h3>
`geolocation` attribute
</h3>
<p>
The <dfn>geolocation</dfn> attribute gives access to location
information associated with the hosting device.
</p>
</section>
</section>
<section id="geolocation_interface" data-dfn-for="Geolocation">
<h3>
`Geolocation` interface
</h3>
<p>
The <dfn>Geolocation</dfn> interface is used by scripts to
programmatically determine the location information associated with
the hosting device. The location information is acquired by applying
a user-agent specific algorithm, creating a {{GeolocationPosition}}
object, and populating that object with appropriate data accordingly.
</p>
<pre class="idl">
[Exposed=Window]
interface Geolocation {
undefined getCurrentPosition(PositionCallback successCallback,
optional PositionErrorCallback errorCallback,
optional PositionOptions options = {});
long watchPosition(PositionCallback successCallback,
optional PositionErrorCallback errorCallback,
optional PositionOptions options = {});
undefined clearWatch(long watchId);
};
callback PositionCallback = undefined (GeolocationPosition position);
callback PositionErrorCallback = undefined (GeolocationPositionError positionError);
</pre>
<section>
<h3>
`getCurrentPosition()` method
</h3>
<p data-tests=
"getCurrentPosition_IDL.https.html, getCurrentPosition_TypeError.html">
The <dfn>getCurrentPosition()</dfn> method takes one, two or three
arguments. When called, it MUST immediately return and then
asynchronously attempt to obtain the current location of the
device. If the attempt is successful, the
|successCallback:PositionCallback| MUST be invoked with a new
{{GeolocationPosition}} object, reflecting the current location of
the device. If the attempt fails, the
|errorCallback:PositionErrorCallback| MUST be invoked with a new
{{GeolocationPositionError}} object, reflecting the reason for the
failure.
</p>
<p>
The implementation of the {{Geolocation/getCurrentPosition()}}
method MUST execute the following set of steps:
</p>
<ol>
<li>Return and continue asynchronously.
</li>
<li>If the <a>environment settings object</a> is a <a>non-secure
context</a> or the <a>current settings object</a>'s [=environment
settings object / responsible document=] is not [=allowed to use=]
the "geolocation" feature:
<ol>
<li>If |errorCallback| was passed, invoke the |errorCallback|
with a newly created {{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} attribute is initialized to
{{GeolocationPositionError/PERMISSION_DENIED}}.
</li>
<li>Terminate this algorithm.
</li>
</ol>
</li>
<li>If a cached {{GeolocationPosition}} object, whose age is no
greater than the value of the {{PositionOptions/maximumAge}}
variable, is available, invoke the |successCallback| with the
cached {{GeolocationPosition}} object as a parameter and exit this
set of steps.
</li>
<li>If the value of the timeout variable is 0, invoke the
|errorCallback| (if present) with a new
{{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} attribute is set to
{{GeolocationPositionError.TIMEOUT}} and exit this set of steps.
</li>
<li>Start a location acquisition operation (e.g. by invoking a
platform-specific API), possibly taking into account the value of
the {{PositionOptions/enableHighAccuracy}} variable.
</li>
<li>Start a timer that will fire after the number of milliseconds
denoted by the value of the timeout variable. When the timer fires,
cancel any ongoing location acquisition operations associated with
this instance of the steps, invoke the |errorCallback| (if present)
with a new {{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} attribute is set to
{{GeolocationPositionError.TIMEOUT}}, and exit this set of steps.
</li>
<li>If the operation completes successfully before the timeout
expires, cancel the pending timer, invoke the |successCallback|
with a new {{GeolocationPosition}} object that reflects the result
of the acquisition operation and exit this set of steps.
</li>
<li>If the operation fails before the timeout expires, cancel the
pending timer and invoke the |errorCallback| (if present) with a
new {{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} is set to
{{GeolocationPositionError.POSITION_UNAVAILABLE}}.
</li>
</ol>
</section>
<section>
<h3>
`watchPosition()` method
</h3>
<p>
The <dfn>watchPosition()</dfn> method takes one, two or three
arguments. When called, immediately return a long value that
uniquely identifies a <a>watch process</a> and continue
asynchronously.
</p>
<ol>
<li>If the <a>environment settings object</a> is a <a>non-secure
context</a> or the <a>current settings object</a>'s [=environment
settings object / responsible document=] is not [=allowed to use=]
the "geolocation" feature:
<ol>
<li>If |errorCallback| was passed, invoke the |errorCallback|
with a newly created {{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} attribute is initialized to
{{GeolocationPositionError/PERMISSION_DENIED}}.
</li>
<li>Terminate this algorithm.
</li>
</ol>
</li>
<li>
<p>
Otherwise, start the watch operation. This operation MUST first
attempt to obtain the current location of the device. If the
attempt is successful, the |successCallback| MUST be invoked
with a new {{GeolocationPosition}} object, reflecting the
current location of the device. If the attempt fails, the
|errorCallback| MUST be invoked with a new
{{GeolocationPositionError}} object, reflecting the reason for
the failure. The <a>watch process</a> then MUST continue to
monitor the position of the device and invoke the appropriate
callback every time this position changes. The <a>watch
process</a> MUST continue until the
{{Geolocation/clearWatch()}} method is called with the
corresponding identifier.
</p>
</li>
</ol>
<p>
The implementation of the <dfn>watch process</dfn> MUST execute the
following set of steps:
</p>
<ol>
<li>If a cached {{GeolocationPosition}} object, whose age is no
greater than the value of the maximumAge variable, is available,
invoke the |successCallback| with the cached
{{GeolocationPosition}} object as a parameter.
</li>
<li>Register to receive system events that indicate that the
position of the device MAY have changed (e.g. by listening or
polling for changes in WiFi or cellular signals).
</li>
<li>Start a location acquisition operation (e.g. by invoking a
platform-specific API), possibly taking into account the value of
the |enableHighAccuracy| variable (see the definition of
{{PositionOptions/enableHighAccuracy}} for details).
</li>
<li>Run the following <dfn>acquisition steps</dfn>:
<ol>
<li>If the timer is not already running, start a timer that
will fire after the number of milliseconds denoted by the value
of the timeout variable. When the timer fires, invoke the
|errorCallback| (if present) with a new
{{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} attribute is set to
{{GeolocationPositionError.TIMEOUT}} and jump to the <a>wait
for a system event to be received</a> step.
</li>
<li>If the location acquisition operation successfully yields a
new position before the timeout expires, perform the following
two steps:
<ol>
<li>Cancel the pending timer. Note that the timer MUST be
restarted once this algorithm jumps back to the beginning
of the acquisition steps.
</li>
<li>If the <dfn>new position differs significantly from the
previous position</dfn>, invoke the |successCallback| with
a new {{GeolocationPosition}} object that reflects the
result of the acquisition operation. This step MAY be
subject to callback [=rate limitation=].
</li>
</ol>
</li>
<li>Else, if the location acquisition operation reports an
error before the {{PositionOptions/timeout}} expires, invoke
the |errorCallback| (if present) with a new
{{GeolocationPositionError}} object whose
{{GeolocationPositionError/code}} is set to
{{GeolocationPositionError.POSITION_UNAVAILABLE}}. This step
MAY be subject to callback [=rate limitation=].
</li>
</ol>
</li>
<li>
<dfn>Wait for a system event to be received</dfn>. When such an
event is received jump to the <a>acquisition steps</a> above.
</li>
</ol>
<p class="note">
If the <a>new position differs significantly from the previous
position</a> in the <a>watch process</a>, the |successCallback| is
only invoked when a new position is obtained and this position
differs significantly from the previously reported position. The
definition of what constitutes a significant difference is left to
the implementation. Furthermore, in steps 4.2.2 and 4.3,
implementations MAY impose a <dfn data-lt="rate limitation">rate
limit</dfn> on the frequency of callbacks so as to avoid
inadvertently consuming a disproportionate amount of resources.
</p>
<p data-tests=
"getCurrentPosition_permission_allow.https.html, getCurrentPosition_permission_deny.https.html, watchPosition_permission_deny.https.html">
For both {{Geolocation/getCurrentPosition()}} and
{{Geolocation/watchPosition()}}, the implementation MUST never
invoke the |successCallback| without having first obtained
permission from the user to share location. Furthermore, the
implementation SHOULD always obtain the user's permission to share
location before executing any of the
{{Geolocation/getCurrentPosition()}} or
{{Geolocation/watchPosition()}} steps described above. If the user
grants permission, the appropriate callback MUST be invoked as
described above. If the user denies permission, the |errorCallback|
(if present) MUST be invoked with {{GeolocationPositionError/code}}
set to {{GeolocationPositionError.PERMISSION_DENIED}}, irrespective
of any other errors encountered in the above steps. The time that
is spent obtaining the user permission MUST NOT be included in the
period covered by the {{PositionOptions/timeout}} attribute of the
{{PositionOptions}} parameter. The {{PositionOptions/timeout}}
attribute MUST only apply to the location acquisition operation.
</p>
</section>
<section>
<h3>
`clearWatch()` method
</h3>
<p data-tests="clearWatch_TypeError.html">
The <dfn>clearWatch()</dfn> method takes one argument. When called,
it MUST first check the value of the given <dfn>watchId</dfn>
argument. If this value does not correspond to any previously
started <a>watch process</a>, then the method MUST return
immediately without taking any further action. Otherwise, the
<a>watch process</a> identified by the `watchId` argument MUST be
immediately stopped and no further callbacks MUST be invoked.
</p>
</section>
<section data-dfn-for="PositionCallBack">
<h3>
`PositionCallBack` callback
</h3>
<p>
The <dfn>PositionCallBack</dfn> callback is invoked when a
{{GeolocationPosition}} object is available, resulting from a
cached object or the acquisition operation. The
<a>PositionCallBack</a> callback gets set using the
<dfn>successCallback</dfn> parameter.
</p>
</section>
<section data-dfn-for="PositionErrorCallBack">
<h3>
`PositionErrorCallBack` callback
</h3>
<p>
The <dfn>PositionErrorCallBack</dfn> callback is invoked when a
{{GeolocationPosition}} object is not available, resulting from a
timeout, a permission denied, or an unability to determine the
position of the device. The <a>PositionErrorCallBack</a> callback
gets set using the <dfn>errorCallback</dfn> parameter.
</p>
</section>
</section>
<section id="position_options_interface" data-dfn-for="PositionOptions">
<h3>
<dfn>PositionOptions</dfn> dictionary
</h3>
<p>
The {{Geolocation/getCurrentPosition()}} and
{{Geolocation/watchPosition()}} methods accept {{PositionOptions}}
objects as their third argument.
</p>
<p>
In ECMAScript, {{PositionOptions}} objects are represented using
regular native objects with optional properties named
{{PositionOptions/enableHighAccuracy}}, {{PositionOptions/timeout}}
and {{PositionOptions/maximumAge}}.
</p>
<pre class="idl">
dictionary PositionOptions {
boolean enableHighAccuracy = false;
[Clamp] unsigned long timeout = 0xFFFFFFFF;
[Clamp] unsigned long maximumAge = 0;
};
</pre>
<section>
<h3>
`enableHighAccuracy` member
</h3>
<p data-tests="PositionOptions.https.html">
The <dfn>enableHighAccuracy</dfn> attribute provides a hint that
the application would like to receive the best possible results.
This MAY result in slower response times or increased power
consumption. The user might also deny this capability, or the
device might not be able to provide more accurate results than if
the flag wasn't specified. The intended purpose of this attribute
is to allow applications to inform the implementation that they do
not require high accuracy geolocation fixes and, therefore, the
implementation can avoid using geolocation providers that consume a
significant amount of power (e.g. GPS). This is especially useful
for applications running on battery-powered devices, such as mobile
phones.
</p>
</section>
<section>
<h3>
`timeout` member
</h3>
<p data-tests="PositionOptions.https.html">
The <dfn>timeout</dfn> attribute denotes the maximum length of time
(expressed in milliseconds) that is allowed to pass from the call
to {{Geolocation/getCurrentPosition()}} or
{{Geolocation/watchPosition()}} until the corresponding
|successCallback| is invoked. If the implementation is unable to
successfully acquire a new {{GeolocationPosition}} before the given
timeout elapses, and no other errors have occurred in this
interval, then the corresponding |errorCallback| MUST be invoked
with a {{GeolocationPositionError}} object whose code attribute is
set to {{GeolocationPositionError.TIMEOUT}}. Note that the time
that is spent obtaining the user permission is not included in the
period covered by the {{PositionOptions/timeout}} attribute. The
{{PositionOptions/timeout}} attribute only applies to the location
acquisition operation.
</p>
<p>
In case of a {{Geolocation/getCurrentPosition()}} call, the
|errorCallback| would be invoked at most once.
</p>
<p>
In case of a {{Geolocation/watchPosition()}}, the |errorCallback|
could be invoked repeatedly: the first timeout is relative to the
moment {{Geolocation/watchPosition()}} was called or the moment the
user's permission was obtained, if that was necessary. Subsequent
timeouts are relative to the moment when the implementation
determines that the position of the hosting device has changed and
a new {{GeolocationPosition}} object MUST be acquired.
</p>
</section>
<section>
<h3>
`maximumAge` member
</h3>
<p data-tests="PositionOptions.https.html">
The <dfn>maximumAge</dfn> attribute indicates that the application
is willing to accept a cached position whose age is no greater than
the specified time in milliseconds. If
{{PositionOptions/maximumAge}} is set to 0, the implementation MUST
immediately attempt to acquire a new position object. Setting the
{{PositionOptions/maximumAge}} to `Infinity` MUST determine the
implementation to return a cached position regardless of its age.
If an implementation does not have a cached position available
whose age is no greater than the specified
{{PositionOptions/maximumAge}}, then it MUST acquire a new
{{GeolocationPosition}} object. In case of a
{{Geolocation/watchPosition()}}, the {{PositionOptions/maximumAge}}
refers to the first {{GeolocationPosition}} object returned by the
implementation.
</p>
</section>
</section>
<section id="position_interface" data-dfn-for="GeolocationPosition">
<h3>
`GeolocationPosition` interface
</h3>
<pre class="idl">
[Exposed=Window, SecureContext]
interface GeolocationPosition {
readonly attribute GeolocationCoordinates coords;
readonly attribute DOMTimeStamp timestamp;
};
</pre>
<p>
The <dfn>GeolocationPosition</dfn> interface is the container for the
geolocation information returned by this API. This version of the
specification allows one attribute of type {{GeolocationCoordinates}}
and a {{GeolocationPosition/timestamp}}. Future versions of the API
MAY allow additional attributes that provide other information about
this position (e.g. street addresses).
</p>
<section>
<h4>
`coords` attribute
</h4>
<p>
The <dfn>coords</dfn> attribute contains a set of geographic
coordinates together with their associated accuracy, as well as a
set of other optional attributes such as altitude and speed.
</p>
</section>
<section>
<h4>
`timestamp` attribute
</h4>
<p>
The <dfn>timestamp</dfn> attribute represents the time when the
{{GeolocationPosition}} object was acquired and is represented as a
{{DOMTimeStamp}}.
</p>
</section>
</section>
<section id="coordinates_interface" data-dfn-for=
"GeolocationCoordinates">
<h3>
<dfn>GeolocationCoordinates</dfn> interface
</h3>
<pre class="idl">
[Exposed=Window, SecureContext]
interface GeolocationCoordinates {
readonly attribute double latitude;
readonly attribute double longitude;
readonly attribute double? altitude;
readonly attribute double accuracy;
readonly attribute double? altitudeAccuracy;
readonly attribute double? heading;
readonly attribute double? speed;
};
</pre>
<p>
The geographic coordinate reference system used by the attributes in
this interface is the World Geodetic System (2d) [[WGS84]]. No other
reference system is supported.
</p>
<section>
<h4>
`latitude` attribute
</h4>
<p>
The <dfn>latitude</dfn> and <dfn>longitude</dfn> attributes are
geographic coordinates specified in decimal degrees.
</p>
</section>
<section>
<h4>
`altitude` attribute
</h4>
<p>
The <dfn>altitude</dfn> attribute denotes the height of the
position, specified in meters above the [[WGS84]] ellipsoid. If the
implementation cannot provide altitude information, the value of
this attribute MUST be null.
</p>
</section>
<section>
<h4>
`accuracy` attribute
</h4>
<p>
The <dfn>accuracy</dfn> attribute denotes the accuracy level of the
latitude and longitude coordinates. It is specified in meters and
MUST be supported by all implementations. The value of the accuracy
attribute MUST be a non-negative real number.
</p>
</section>
<section>
<h4>
`altitudeAccuracy` attribute
</h4>
<p>
The <dfn>altitudeAccuracy</dfn> attribute is specified in meters.
If the implementation cannot provide altitude information, the
value of this attribute MUST be null. Otherwise, the value of the
altitudeAccuracy attribute MUST be a non-negative real number.
</p>
<p>
The {{GeolocationCoordinates/accuracy}} and
{{GeolocationCoordinates/altitudeAccuracy}} values returned by an
implementation SHOULD correspond to a 95% confidence level.
</p>
</section>
<section>
<h4>
`heading` attribute
</h4>
<p>
The <dfn>heading</dfn> attribute denotes the direction of travel of
the hosting device and is specified in degrees, where 0° ≤ heading
< 360°, counting clockwise relative to the true north. If the
implementation cannot provide heading information, the value of
this attribute MUST be null. If the hosting device is stationary
(i.e. the value of the {{GeolocationCoordinates/speed}} attribute
is 0), then the value of the heading attribute MUST be NaN.
</p>
</section>
<section>
<h4>
`speed` attribute
</h4>
<p>
The <dfn>speed</dfn> attribute denotes the magnitude of the
horizontal component of the hosting device's current velocity and
is specified in meters per second. If the implementation cannot
provide speed information, the value of this attribute MUST be
null. Otherwise, the value of the speed attribute MUST be a
non-negative real number.
</p>
</section>
</section>
<section id="position_error_interface" data-dfn-for=
"GeolocationPositionError">
<h3>
<dfn>GeolocationPositionError</dfn> interface
</h3>
<pre class="idl">
[Exposed=Window]
interface GeolocationPositionError {
const unsigned short PERMISSION_DENIED = 1;
const unsigned short POSITION_UNAVAILABLE = 2;
const unsigned short TIMEOUT = 3;
readonly attribute unsigned short code;
readonly attribute DOMString message;
};
</pre>
<section>
<h4>
`code` attribute
</h4>
<p>
The <dfn>code</dfn> attribute MUST return the appropriate code from
the following list:
</p>
<dl>
<dt>
<dfn>PERMISSION_DENIED</dfn> (numeric value 1)
</dt>
<dd>
The location acquisition process failed because the document does
not have permission to use the Geolocation API.
</dd>
<dt>
<dfn>POSITION_UNAVAILABLE</dfn> (numeric value 2)
</dt>
<dd>
The position of the device could not be determined. For instance,
one or more of the location providers used in the location
acquisition process reported an internal error that caused the
process to fail entirely.
</dd>
<dt>
<dfn>TIMEOUT</dfn> (numeric value 3)
</dt>
<dd>
The length of time specified by the {{PositionOptions/timeout}}
property has elapsed before the implementation could successfully
acquire a new {{GeolocationPosition}} object.
</dd>
</dl>
</section>
<section>
<h4>
`message` attribute
</h4>
<p>
The <dfn>message</dfn> attribute MUST return an error message
describing the details of the error encountered. This attribute is
primarily intended for debugging and developers SHOULD NOT use it
directly in their application user interface.
</p>
</section>
</section>
</section>
<section>
<h2>
Permissions policy
</h2>
<p>
The <cite>Geolocation API</cite> defines a [=policy-controlled
feature=] identified by the string "geolocation". Its [=default
allowlist=] is `["self"]`.
</p>
<aside class="note">
<p>
The <a>default allowlist</a> of `["self"]` allows Geolocation usage
in same-origin nested frames but prevents third-party content from
using the API.
</p>
<p>
Third-party usage can be selectively enabled by adding
`allow="geolocation"` attribute to an [^iframe^] element:
</p>
<pre class="example html" title=
"Enabling Geolocation on third-party content">
<iframe src="https://third-party.com" allow="geolocation"/></iframe>
</pre>
<p>
Alternatively, the Geolocation API can be disabled completely in a
first-party context by specifying the permission policy in a HTTP
response header:
</p>
<pre class="example http" title="Feature Policy over HTTP">
Permissions-Policy: geolocation 'none'
</pre>
<p>
See [[[permissions-policy]]] for more details.
</p>
</aside>
</section>
<section id="usecases" class="informative">
<h2>
Use-Cases and Requirements
</h2>
<section id="usecases_section">
<h3>
Use-Cases
</h3>
<section id="usecase_find_poi">
<h4>
Find points of interest in the user's area
</h4>
<p>
Someone visiting a foreign city could access a Web application that
allows users to search or browse through a database of tourist
attractions. Using the Geolocation API, the Web application has
access to the user's approximate position and it is therefore able