@tauri-apps/plugin-geolocation

Get and track the device’s current position, mirroring the W3C Geolocation API.

Functions

checkPermissions()

function checkPermissions(): Promise<PermissionStatus>;

Defined in: plugins/geolocation/guest-js/index.ts:216

Returns the current state of the geolocation permissions. Rejects if location services are disabled on the device.

Example

import { checkPermissions } from '@tauri-apps/plugin-geolocation';
const permission = await checkPermissions();

Returns

Promise<PermissionStatus>

A promise resolving to the current PermissionStatus.

Since

2.0.0

---

clearWatch()

function clearWatch(channelId: number): Promise<void>;

Defined in: plugins/geolocation/guest-js/index.ts:198

Stops the position watcher registered with watchPosition.

Example

import { clearWatch } from '@tauri-apps/plugin-geolocation';
await clearWatch(watchId);

Parameters

Parameter	Type	Description
channelId	number	The id returned by watchPosition.

Returns

Promise<void>

Since

2.0.0

---

getCurrentPosition()

function getCurrentPosition(options?: PositionOptions): Promise<Position>;

Defined in: plugins/geolocation/guest-js/index.ts:178

Returns the device’s current position, similar to the W3C navigator.geolocation.getCurrentPosition API.

Example

import { getCurrentPosition } from '@tauri-apps/plugin-geolocation';
const position = await getCurrentPosition();

Parameters

Parameter	Type	Description
options?	PositionOptions	Configuration for the position request.

Returns

Promise<Position>

A promise resolving to the current Position.

Since

2.0.0

---

requestPermissions()

function requestPermissions(permissions: PermissionType[] | null): Promise<PermissionStatus>;

Defined in: plugins/geolocation/guest-js/index.ts:233

Requests the given geolocation permissions, prompting the user if needed. Rejects if location services are disabled on the device.

Example

import { requestPermissions } from '@tauri-apps/plugin-geolocation';
const permission = await requestPermissions(['location']);

Parameters

Parameter	Type	Description
permissions	| PermissionType[] | null	The permissions to request, or null to request all of them.

Returns

Promise<PermissionStatus>

A promise resolving to the resulting PermissionStatus.

Since

2.0.0

---

watchPosition()

function watchPosition(options: PositionOptions, cb: (location: Position | null, error?: string) => void): Promise<number>;

Defined in: plugins/geolocation/guest-js/index.ts:146

Registers a callback that is invoked with the device’s position whenever it changes, similar to the W3C navigator.geolocation.watchPosition API. Pass the returned id to clearWatch to stop watching.

Example

import { watchPosition } from '@tauri-apps/plugin-geolocation';
const watchId = await watchPosition(
  { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 },
  (position, error) => {
    if (error) {
      console.error(error)
    } else {
      console.log(position)
    }
  }
);

Parameters

Parameter	Type	Description
options	PositionOptions	Configuration for the position watcher.
cb	(location: Position | null, error?: string) => void	Callback invoked with the new Position on success, or null and an error message when a read fails.

Returns

Promise<number>

A promise resolving to the id of the registered watcher.

Since

2.0.0

Type Aliases

Coordinates

type Coordinates = {
  accuracy: number;
  altitude: number | null;
  altitudeAccuracy: number | null;
  heading: number | null;
  latitude: number;
  longitude: number;
  speed: number | null;
};

Defined in: plugins/geolocation/guest-js/index.ts:21

The GPS coordinates of a Position, along with the accuracy of each reading.

Properties

Property	Type	Description	Defined in
accuracy	number	Accuracy level of the latitude and longitude coordinates in meters.	plugins/geolocation/guest-js/index.ts:33
altitude	number | null	The altitude the user is at, if available.	plugins/geolocation/guest-js/index.ts:42
altitudeAccuracy	number | null	Accuracy level of the altitude coordinate in meters, if available. Available on all iOS versions and on Android 8 and above.	plugins/geolocation/guest-js/index.ts:38
heading	number | null	The heading the user is facing, if available.	plugins/geolocation/guest-js/index.ts:50
latitude	number	Latitude in decimal degrees.	plugins/geolocation/guest-js/index.ts:25
longitude	number	Longitude in decimal degrees.	plugins/geolocation/guest-js/index.ts:29
speed	number | null	The speed the user is traveling, in meters per second, if available.	plugins/geolocation/guest-js/index.ts:46

---

PermissionStatus

type PermissionStatus = {
  coarseLocation: PermissionState;
  location: PermissionState;
};

Defined in: plugins/geolocation/guest-js/index.ts:56

The current permission state for the geolocation APIs.

Properties

Property	Type	Description	Defined in
coarseLocation	PermissionState	Permissions state for the coarseLoaction alias. On Android it requests/checks ACCESS_COARSE_LOCATION. On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) and Precise location (ACCESS_FINE_LOCATION). On iOS it will have the same value as the location alias.	plugins/geolocation/guest-js/index.ts:74
location	PermissionState	Permission state for the location alias. On Android it requests/checks both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions. On iOS it requests/checks location permissions.	plugins/geolocation/guest-js/index.ts:64

---

PermissionType

type PermissionType = "location" | "coarseLocation";

Defined in: plugins/geolocation/guest-js/index.ts:84

The individual permission aliases that can be requested with requestPermissions.

location maps to both the coarse and fine location permissions on Android and to the standard location permission on iOS. coarseLocation maps to the coarse location permission only on Android, and behaves the same as location on iOS.

---

Position

type Position = {
  coords: Coordinates;
  timestamp: number;
};

Defined in: plugins/geolocation/guest-js/index.ts:89

A geolocation reading, as returned by getCurrentPosition and passed to the callback of watchPosition.

Properties

Property	Type	Description	Defined in
coords	Coordinates	The GPS coordinates along with the accuracy of the data.	plugins/geolocation/guest-js/index.ts:97
timestamp	number	Creation time for these coordinates, in milliseconds since the Unix epoch.	plugins/geolocation/guest-js/index.ts:93

---

PositionOptions

type PositionOptions = {
  enableHighAccuracy: boolean;
  maximumAge: number;
  timeout: number;
};

Defined in: plugins/geolocation/guest-js/index.ts:103

Options used to configure a getCurrentPosition or watchPosition request.

Properties

Property	Type	Description	Defined in
enableHighAccuracy	boolean	High accuracy mode (such as GPS, if available) Will be ignored on Android 12+ if users didn’t grant the ACCESS_FINE_LOCATION permission (coarseLocation permission).	plugins/geolocation/guest-js/index.ts:108
maximumAge	number	The maximum age in milliseconds of a possible cached position that is acceptable to return. Default: 0 Ignored on iOS	plugins/geolocation/guest-js/index.ts:120
timeout	number	The maximum wait time in milliseconds for location updates. On Android the timeout gets ignored for getCurrentPosition. Ignored on iOS	plugins/geolocation/guest-js/index.ts:114