Geolocation - HTML5 and JavaScript Web Apps - page 131

position . coords . accuracy //accuracy level of latitude and longitude coordinates
position . coords . altitudeAccuracy //specified in meters
position . coords . heading // direction of travel of the hosting device in degrees
position . coords . speed //the device's current velocity (meters per second)
Only the latitude , longitude , and accuracy properties are guaranteed to be available.
The rest might come back null, depending on the capabilities of the user's device and
the backend positioning server that it talks to.
The getCurrentPosition() function has an optional third argument, a PositionOp
tions object:
navigator . geolocation . getCurrentPosition ( successCallback , errorCallback ,
{ enableHighAccuracy : true , timeout : 10000 , maximumAge : 6000 });
The enableHighAccuracy attribute provides a hint that the application would like to
receive the best possible results. If this attribute is true, the device can support it, and
the user consents, then the device will try to provide an exact location. Using this at‐
tribute may result in slower response times or increased power consumption. The user
might also deny this capability, or the device might have more accurate results to provide.
The intended purpose of this attribute is to allow applications to inform the implemen‐
tation that they do not require high accuracy Geolocation fixes and, therefore, the im‐
plementation can avoid using Geolocation providers that consume a significant amount
of power (think GPS).
The timeout property is the number of milliseconds your web application is willing to
wait for a position. This timer doesn't start counting down until after the user gives
permission to share position data. You're not timing the user; you're timing the network.
The maximumAge attribute indicates that the application is willing to accept a cached
position whose age is no greater than the specified time in milliseconds. This gives you
a window of time to pull a cached location from the user device. By defining this at‐
tribute, you are saying that you're fine with where this device was located at x millisec‐
onds in the past.
Your web app will dictate exactly the specificity of your Geolocation needs. So keep in
mind battery life and latencies on the user device when you use the above properties. If
you need to track the location of the user continuously, the spec defines the watchPosi
tion() function. It has the same structure as getCurrentPosition() and will call the
successCallback whenever the device position changes:
navigator . geolocation . watchPosition ( successCallback , errorCallback ,
{ enableHighAccuracy : true , timeout : 10000 , maximumAge : 6000 });
Use watchPosition() with care in Mobile Safari running on iOS5. As of this writing,
there is a known issue: the page will run for roughly four minutes, after which the user
will receive a “JavaScript execution exceeded timeout” error. To work around the watch
Position() issue on iOS5, you can implement the following code using getCurrentPo
sition() with setInterval() :