@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:

<!-- Geolocation Plugin -->
<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

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.

Since: 1.0.0

clearWatch(...)

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

Clear a given watch

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.

Since: 1.0.0

Interfaces

Position

PositionOptions

ClearWatchOptions

PermissionStatus

GeolocationPluginPermissions

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: