1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250# @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
```bash
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`](https://github.com/ionic-team/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`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) in the [iOS Guide](https://capacitorjs.com/docs/ios) for more information on setting iOS permissions in Xcode
## Android
This plugin requires the following permissions be added to your `AndroidManifest.xml`:
```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](https://capacitorjs.com/docs/android/configuration#setting-permissions) in the [Android Guide](https://capacitorjs.com/docs/android) for more information on setting Android permissions.
## API
<docgen-index>
* [`getCurrentPosition(...)`](#getcurrentposition)
* [`watchPosition(...)`](#watchposition)
* [`clearWatch(...)`](#clearwatch)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions(...)`](#requestpermissions)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
</docgen-index>
For list of error codes, see [Errors](#errors)
<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
### getCurrentPosition(...)
```typescript
getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>
```
Get the current GPS location of the device
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | <code><a href="#positionoptions">PositionOptions</a></code> |
**Returns:** <code>Promise<<a href="#position">Position</a>></code>
**Since:** 1.0.0
--------------------
### watchPosition(...)
```typescript
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`** | <code><a href="#positionoptions">PositionOptions</a></code> |
| **`callback`** | <code><a href="#watchpositioncallback">WatchPositionCallback</a></code> |
**Returns:** <code>Promise<string></code>
**Since:** 1.0.0
--------------------
### clearWatch(...)
```typescript
clearWatch(options: ClearWatchOptions) => Promise<void>
```
Clear a given watch
| Param | Type |
| ------------- | --------------------------------------------------------------- |
| **`options`** | <code><a href="#clearwatchoptions">ClearWatchOptions</a></code> |
**Since:** 1.0.0
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise<PermissionStatus>
```
Check location permissions. Will throw if system location services are disabled.
**Returns:** <code>Promise<<a href="#permissionstatus">PermissionStatus</a>></code>
**Since:** 1.0.0
--------------------
### requestPermissions(...)
```typescript
requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>
```
Request location permissions. Will throw if system location services are disabled.
Not available on web.
| Param | Type |
| ----------------- | ------------------------------------------------------------------------------------- |
| **`permissions`** | <code><a href="#geolocationpluginpermissions">GeolocationPluginPermissions</a></code> |
**Returns:** <code>Promise<<a href="#permissionstatus">PermissionStatus</a>></code>
**Since:** 1.0.0
--------------------
### Interfaces
#### Position
| Prop | Type | Description | Since |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----- |
| **`timestamp`** | <code>number</code> | Creation timestamp for coords | 1.0.0 |
| **`coords`** | <code>{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number \| null; altitude: number \| null; speed: number \| null; heading: number \| null; }</code> | The GPS coordinates along with the accuracy of the data | 1.0.0 |
#### PositionOptions
| Prop | Type | Description | Default | Since |
| ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
| **`enableHighAccuracy`** | <code>boolean</code> | 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). | <code>false</code> | 1.0.0 |
| **`timeout`** | <code>number</code> | The maximum wait time in milliseconds for location updates. | <code>10000</code> | 1.0.0 |
| **`maximumAge`** | <code>number</code> | The maximum age in milliseconds of a possible cached position that is acceptable to return | <code>0</code> | 1.0.0 |
| **`minimumUpdateInterval`** | <code>number</code> | The minimum update interval for `watchPosition`. Not to be confused with `interval`. 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. | <code>5000</code> | 6.1.0 |
| **`interval`** | <code>number</code> | Desired interval in milliseconds to receive location updates in `watchPosition`. For very low values of `interval` (a couple seconds or less), the platform may not guarantee timely location updates - they may take longer than specified. The platform may also be able to provide location updates faster than `interval`. You may use `minimumUpdateInterval` to control that behavior. For backwards compatiblity with version 7.1.x, if no value is passed, the default value of this parameter is that of `timeout`. This parameter is only available for Android. It has no effect on iOS or Web platforms. | <code>`timeout`</code> | 8.0.0 |
| **`enableLocationFallback`** | <code>boolean</code> | Whether to fall back to the Android framework's `LocationManager` in case Google Play Service's location settings checks fail. This can happen for multiple reasons - e.g. device has no Play Services or device has no network connection (Airplane Mode) If set to `false`, failures are propagated to the caller. Note that `LocationManager` may not be as effective as Google Play Services implementation. If the device's in airplane mode, only the GPS provider is used, which may take longer to return a location, depending on GPS signal. This means that to receive location in such circumstances, you may need to provide a higher timeout. This parameter is only available for Android. It has no effect on iOS or Web platforms. | <code>true</code> | 8.0.0 |
#### ClearWatchOptions
| Prop | Type |
| -------- | ------------------------------------------------- |
| **`id`** | <code><a href="#callbackid">CallbackID</a></code> |
#### PermissionStatus
| Prop | Type | Description | Since |
| -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`location`** | <code><a href="#permissionstate">PermissionState</a></code> | 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`** | <code><a href="#permissionstate">PermissionState</a></code> | 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`** | <code>GeolocationPermissionType[]</code> |
### Type Aliases
#### WatchPositionCallback
<code>(position: <a href="#position">Position</a> | null, err?: any): void</code>
#### CallbackID
<code>string</code>
#### PermissionState
<code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>
#### GeolocationPermissionType
<code>'location' | 'coarseLocation'</code>
</docgen-api>
### 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, iOS | 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. |
| OS-PLUG-GLOC-0017 | Android | Unable to retrieve location because device has both Network and Location turned off. |