@capacitor/geolocation

The Geolocation API provides simple methods for getting and tracking the current position of the device using GPS, along with altitude, heading, and speed information if available.

Install

npm install @capacitor/geolocation
npx cap sync

iOS

Apple requires privacy descriptions to be specified in Info.plist for location information:

• NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description)
• NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)

[!NOTE] This Capacitor plugin does not support background geolocation directly. However, it relies on ion-ios-geolocation, which can report location in the background. As a result, Apple requires you to include a NSLocationAlwaysAndWhenInUseUsageDescription entry in your Info.plist. Since this permission prompt won’t appear to users, you can safely use the same description string as for NSLocationWhenInUseUsageDescription.

Read about Configuring Info.plist in the iOS Guide for more information on setting iOS permissions in Xcode

Android

This plugin requires the following permissions be added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location.gps" />

The first two permissions ask for location data, both fine and coarse, and the last line is optional but necessary if your app requires GPS to function. You may leave it out, though keep in mind that this may mean your app is installed on devices lacking GPS hardware.

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

API

• getCurrentPosition(...)
• watchPosition(...)
• clearWatch(...)
• checkPermissions()
• requestPermissions(...)
• Interfaces
• Type Aliases

For list of error codes, see Errors

getCurrentPosition(...)

getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>

Get the current GPS location of the device

Param	Type
options	PositionOptions

Returns: Promise<Position>

Since: 1.0.0

---

watchPosition(...)

watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>

Set up a watch for location changes. Note that watching for location changes can consume a large amount of energy. Be smart about listening only when you need to.

Param	Type
options	PositionOptions
callback	WatchPositionCallback

Returns: Promise<string>

Since: 1.0.0

---

clearWatch(...)

clearWatch(options: ClearWatchOptions) => Promise<void>

Clear a given watch

Param	Type
options	ClearWatchOptions

Since: 1.0.0

---

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check location permissions. Will throw if system location services are disabled.

Returns: Promise<PermissionStatus>

Since: 1.0.0

---

requestPermissions(...)

requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>

Request location permissions. Will throw if system location services are disabled.

Not available on web.

Param	Type
permissions	GeolocationPluginPermissions

Returns: Promise<PermissionStatus>

Since: 1.0.0

---

Interfaces

Position

Prop	Type	Description	Since
timestamp	number	Creation timestamp for coords	1.0.0
coords	{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number | null; altitude: number | null; speed: number | null; heading: number | null; }	The GPS coordinates along with the accuracy of the data	1.0.0

PositionOptions

Prop	Type	Description	Default	Since
enableHighAccuracy	boolean	High accuracy mode (such as GPS, if available) On Android 12+ devices it will be ignored if users didn't grant ACCESS_FINE_LOCATION permissions (can be checked with location alias).	false	1.0.0
timeout	number	The maximum wait time in milliseconds for location updates. In Android, since version 7.1.0 of the plugin, it is also used to determine the interval of location updates for watchPosition.	10000	1.0.0
maximumAge	number	The maximum age in milliseconds of a possible cached position that is acceptable to return	0	1.0.0
minimumUpdateInterval	number	The minumum update interval for location updates. If location updates are available faster than this interval then an update will only occur if the minimum update interval has expired since the last location update. This parameter is only available for Android. It has no effect on iOS or Web platforms.	5000	6.1.0

ClearWatchOptions

Prop	Type
id	CallbackID

PermissionStatus

Prop	Type	Description	Since
location	PermissionState	Permission state for location alias. On Android it requests/checks both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions. On iOS and web it requests/checks location permission.	1.0.0
coarseLocation	PermissionState	Permission state for coarseLocation alias. On Android it requests/checks ACCESS_COARSE_LOCATION. On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) or Precise location (ACCESS_FINE_LOCATION), so this alias can be used if the app doesn't need high accuracy. On iOS and web it will have the same value as location alias.	1.2.0

GeolocationPluginPermissions

Prop	Type
permissions	GeolocationPermissionType[]

Type Aliases

WatchPositionCallback

(position: Position | null, err?: any): void

CallbackID

string

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

GeolocationPermissionType

'location' | 'coarseLocation'

Errors

The plugin returns specific errors with specific codes on native Android and iOS. Web does not follow this standard for errors.

The following table list all the plugin errors:

Error code	Platform(s)	Message
OS-PLUG-GLOC-0002	Android, iOS	There was en error trying to obtain the location.
OS-PLUG-GLOC-0003	Android, iOS	Location permission request was denied.
OS-PLUG-GLOC-0004	iOS	The 'getCurrentPosition' input parameters aren't valid.
OS-PLUG-GLOC-0005	iOS	The 'watchPosition' input parameters aren't valid.
OS-PLUG-GLOC-0006	iOS	The 'clearWatch' input parameters aren't valid.
OS-PLUG-GLOC-0007	Android, iOS	Location services are not enabled.
OS-PLUG-GLOC-0008	iOS	Application's use of location services was restricted.
OS-PLUG-GLOC-0009	Android	Request to enable location was denied.
OS-PLUG-GLOC-0010	Android	Could not obtain location in time. Try with a higher timeout.
OS-PLUG-GLOC-0011	Android	Timeout needs to be a positive value.
OS-PLUG-GLOC-0012	Android	WatchId not found.
OS-PLUG-GLOC-0013	Android	WatchId needs to be provided.
OS-PLUG-GLOC-0014	Android	Google Play Services error user resolvable.
OS-PLUG-GLOC-0015	Android	Google Play Services error.
OS-PLUG-GLOC-0016	Android	Location settings error.