Missed the live Ionic Event? Check out all the product announcements, new releases, and more.

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

NSLocationAlwaysUsageDescription (Privacy - Location Always Usage Description)
NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)

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

Android

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

<!-- Geolocation API -->
<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.

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

$playServicesLocationVersion version of com.google.android.gms:play-services-location (default: 17.1.0)

Example

import { Geolocation } from '@capacitor/geolocation';

const printCurrentPosition = async () {
  const coordinates = await Geolocation.getCurrentPosition();

  console.log('Current position:', coordinates);
};

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) => 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: 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

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request location permissions

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)	`false`	1.0.0
`timeout`	`number`	The maximum wait time in milliseconds for location updates	`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

ClearWatchOptions

Prop	Type
`id`	`CallbackID`

PermissionStatus

Prop	Type
`location`	`PermissionState`

Type Aliases

WatchPositionCallback

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

CallbackID

string

PermissionState

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

Contribute ->