Skip to main content
Version: v5

@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@latest-5
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: 21.0.1)

Exampleโ€‹

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

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

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

APIโ€‹

getCurrentPosition(...)โ€‹

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

Get the current GPS location of the device

ParamType
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.

ParamType
options
PositionOptions
callback
WatchPositionCallback

Returns: Promise<string>

Since: 1.0.0


clearWatch(...)โ€‹

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

Clear a given watch

ParamType
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.

ParamType
permissions
GeolocationPluginPermissions

Returns:

Promise<PermissionStatus>

Since: 1.0.0


Interfacesโ€‹

Positionโ€‹

PropTypeDescriptionSince
timestampnumberCreation timestamp for coords1.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 data1.0.0

PositionOptionsโ€‹

PropTypeDescriptionDefaultSince
enableHighAccuracybooleanHigh 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).false1.0.0
timeoutnumberThe maximum wait time in milliseconds for location updates. In Android, since version 4.0.0 of the plugin, timeout gets ignored for getCurrentPosition.100001.0.0
maximumAgenumberThe maximum age in milliseconds of a possible cached position that is acceptable to return01.0.0

ClearWatchOptionsโ€‹

PropType
id
CallbackID

PermissionStatusโ€‹

PropTypeDescriptionSince
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โ€‹

PropType
permissionsGeolocationPermissionType[]

Type Aliasesโ€‹

Positionโ€‹

A Position is an array of coordinates. https://tools.ietf.org/html/rfc7946#section-3.1.1 Array should contain between two and three elements. The previous GeoJSON specification allowed more elements (e.g., which could be used to represent M values), but the current specification only allows X, Y, and (optionally) Z to be defined.

number[]

WatchPositionCallbackโ€‹

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

CallbackIDโ€‹

string

PermissionStateโ€‹

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

GeolocationPermissionTypeโ€‹

'location' | 'coarseLocation'