Location

Access the device GPS, track location changes in real time, and set up geofences that trigger events when the user enters or exits a region.

Access: startiapp.Location

Methods

`getLocation(options?): Promise<Location>`

Retrieves the device's current location.

Parameters:

Parameter	Type	Required	Description
options	`LocationOptions`	No	Options for timeout, caching, and accuracy

Returns: Promise<Location> —The current location.

Example:

// Basic usage
const location = await startiapp.Location.getLocation();
console.log(location.latitude, location.longitude);

// With options
const location = await startiapp.Location.getLocation({
  timeoutInMs: 10000,
  maxAgeInMs: 5000,
  desiredAccuracy: "High",
});

console.log(`Lat: ${location.latitude}, Lng: ${location.longitude}`);
console.log(`Accuracy: ${location.accuracy}m`);

`startLocationListener(options?): Promise<void>`

Starts continuously listening for location changes. Location updates are delivered via the locationChanged event.

Parameters:

Parameter	Type	Required	Description
options	`LocationListeningOptions`	No	Options for update frequency and accuracy

Returns: Promise<void>

Example:

// Listen for location updates
startiapp.Location.addEventListener("locationChanged", (event) => {
  const loc = event.detail;
  console.log(`Moved to: ${loc.latitude}, ${loc.longitude}`);
});

// Start listening with high accuracy, minimum 1 second between updates
await startiapp.Location.startLocationListener({
  minimumTimeInMs: 1000,
  desiredAccuracy: "High",
});

`stopLocationListener(): Promise<void>`

Stops the location listener started by startLocationListener().

Returns: Promise<void>

Example:

await startiapp.Location.stopLocationListener();

`isLocationListenerActive(): Promise<boolean>`

Checks whether the location listener is currently running.

Returns: Promise<boolean> —true if listening.

Example:

const active = await startiapp.Location.isLocationListenerActive();

if (active) {
  console.log("Location tracking is active");
}

`createGeofence(region): Promise<void>`

Creates a geofence region. When the user enters or exits the region, the corresponding event fires.

Parameters:

Parameter	Type	Required	Description
region	`GeofenceRegion`	Yes	The geofence region to create

Returns: Promise<void>

Example:

await startiapp.Location.createGeofence({
  identifier: "office",
  center: { latitude: 55.6761, longitude: 12.5683 },
  radius: { totalKilometers: 0.5 },
  notifyOnEntry: true,
  notifyOnExit: true,
});

`removeGeofence(region): Promise<void>`

Removes a previously created geofence.

Parameters:

Parameter	Type	Required	Description
region	`GeofenceRegion`	Yes	The geofence region to remove (matched by identifier)

Returns: Promise<void>

Example:

await startiapp.Location.removeGeofence({
  identifier: "office",
  center: { latitude: 55.6761, longitude: 12.5683 },
  radius: { totalKilometers: 0.5 },
});

`getGeofences(): Promise<GeofenceRegion[]>`

Returns all currently registered geofences.

Returns: Promise<GeofenceRegion[]>

Example:

const geofences = await startiapp.Location.getGeofences();

geofences.forEach((fence) => {
  console.log(`${fence.identifier}: ${fence.center.latitude}, ${fence.center.longitude}`);
});

`requestAccess(): Promise<void>`

Requests location permission from the user. Shows the platform's native permission dialog.

Returns: Promise<void>

Example:

await startiapp.Location.requestAccess();

`checkAccess(): Promise<PermissionStatus>`

Checks the current location permission status without prompting.

Returns: Promise<PermissionStatus> —Object with a granted boolean.

Example:

const status = await startiapp.Location.checkAccess();

if (!status.granted) {
  await startiapp.Location.requestAccess();
}

Events

`locationChanged`

Fired when the device location changes while the location listener is active.

Event data: Location

Example:

startiapp.Location.addEventListener("locationChanged", (event) => {
  const location = event.detail;
  console.log(`New position: ${location.latitude}, ${location.longitude}`);
  console.log(`Speed: ${location.speed} m/s`);
  console.log(`Mock provider: ${location.isFromMockProvider}`);
});

`onRegionEntered`

Fired when the user enters a geofence region.

Event data: GeofenceRegion

Example:

startiapp.Location.addEventListener("onRegionEntered", (event) => {
  console.log(`Entered region: ${event.detail.identifier}`);
});

`onRegionExited`

Fired when the user exits a geofence region.

Event data: GeofenceRegion

Example:

startiapp.Location.addEventListener("onRegionExited", (event) => {
  console.log(`Exited region: ${event.detail.identifier}`);
});

Types

Location Type

interface Location {
  latitude: number;
  longitude: number;
  altitude?: number | null;
  accuracy?: number | null;
  altitudeAccuracy?: number | null;
  reducedAccuracy: boolean;
  heading?: number | null;
  speed?: number | null;
  isFromMockProvider: boolean;
  timestamp: string;
}

`LocationOptions`

interface LocationOptions {
  /** Maximum time in milliseconds to wait for a location update. */
  timeoutInMs?: number;
  /** Maximum age in milliseconds of a cached location that is acceptable. */
  maxAgeInMs?: number;
  /** The desired accuracy of the location. */
  desiredAccuracy?: LocationAccuracy;
}

`LocationListeningOptions`

interface LocationListeningOptions {
  /** Minimum time in milliseconds between location updates. */
  minimumTimeInMs?: number;
  /** The desired accuracy of the location updates. */
  desiredAccuracy?: LocationAccuracy;
}

`LocationAccuracy`

enum LocationAccuracy {
  /** Default accuracy (Medium), typically 30-500 meters. */
  Default = "Default",
  /** Lowest accuracy, least power, typically 1000-5000 meters. */
  Lowest = "Lowest",
  /** Low accuracy, typically 300-3000 meters. */
  Low = "Low",
  /** Medium accuracy, typically 30-500 meters. */
  Medium = "Medium",
  /** High accuracy, typically 10-100 meters. */
  High = "High",
  /** Best accuracy, most power, typically within 10 meters. */
  Best = "Best",
}

`GeofenceRegion`

interface GeofenceRegion {
  identifier: string;
  center: Position;
  radius: Distance;
  notifyOnEntry?: boolean;
  notifyOnExit?: boolean;
}

`Position`

interface Position {
  latitude: number;
  longitude: number;
}

`Distance`

interface Distance {
  totalKilometers: number;
}

`GeofenceState`

type GeofenceState = "entered" | "exited" | "unknown";

`PermissionStatus`

interface PermissionStatus {
  granted: boolean;
}

On this page