Geolocation (GPS) Guide

Overview

The Geolocation API allows developers to determine the physical location of a device using GPS. The API design is based upon the Geolocation Web API but does not use the navigator object.

The Device API and Companion API both expose an identical implementation of the GPS API. The Device API uses the embedded GPS receiver when available. On devices without a built-in GPS receiver, the Device API falls back to using Connected GPS from the user's mobile phone. The Companion API uses only the phone's geolocation services.

Note: Fitbit Versa 3 and Fitbit Sense have embedded GPS receivers.

Latitude and longitude coordinates are provided in Decimal degrees (DD) format.

27.380262, 33.632421

NOTE: Use of this API requires the access_location and run_background permissions.

Peek the Current Location

Obtain the current location coordinates by making an asynchronous call to getCurrentPosition().

import { geolocation } from "geolocation";

geolocation.getCurrentPosition(locationSuccess, locationError, {
  timeout: 60 * 1000
});

function locationSuccess(position) {
  console.log(
    "Latitude: " + position.coords.latitude,
    "Longitude: " + position.coords.longitude
  );
}

function locationError(error) {
  console.log("Error: " + error.code, "Message: " + error.message);
}

Note: GPS does not work well indoors. You will only receive the success callback when a 3D-fix is obtained, this may require up to 4 satellites.

Monitoring the Current Location

If you need to continuously monitor the user's GPS coordinates, you can use the watchPosition() function. It works almost the same way as getCurrentPosition(), but the callback is called each time the location changes.

import { geolocation } from "geolocation";

var watchID = geolocation.watchPosition(locationSuccess, locationError, { timeout: 60 * 1000 });

function locationSuccess(position) {
    console.log("Latitude: " + position.coords.latitude,
                "Longitude: " + position.coords.longitude);
}

function locationError(error) {
  console.log("Error: " + error.code,
              "Message: " + error.message);
}

To stop monitoring for location updates, call clearWatch() passing the ID generated on initialization.

geolocation.clearWatch(watchID);

File System Guide

Glossary Guide