# @nativescript/geolocation

> Provides API for getting and monitoring location for NativeScript app.

Latest version **9.0.0** (published 2024-07-22) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @nativescript/geolocation
pnpm add @nativescript/geolocation
yarn add @nativescript/geolocation
bun add @nativescript/geolocation
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 9.0.0 |
| Published | 2024-07-22 |
| First published | 2020-08-06 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 97.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 206 |
| Author | NativeScript |
| Maintainers | nativescript-user, tns-bot, lini, tachev, rosen-vladimirov, stoskov, rosen_vladimirov, walkerrunpdx, bradmartin, davecoffin, rigor789, nativescript-bot, multishiv19, eddyverbruggen, edusperoni, facetious, tdermendjiev, sis0k0 |
| Keywords | NativeScript, JavaScript, TypeScript, iOS, Android |

## Links

- npm: https://www.npmjs.com/package/@nativescript/geolocation
- Repository: https://github.com/NativeScript/plugins
- Issues: https://github.com/NativeScript/plugins/issues
- npm.io page: https://npm.io/package/@nativescript/geolocation

## Dependencies (1)

- [@nativescript-community/perms](https://npm.io/package/@nativescript-community/perms.md) ^2.3.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 9.0.0 (latest) — 2024-07-22
- 9.0.0-rc.0 (rc) — 2024-07-20
- 8.2.1-beta.0 (beta) — 2023-07-10
- 8.3.1 — 2023-10-23
- 8.3.0 — 2023-10-23
- 8.2.1 — 2023-07-11
- 8.2.0 — 2023-04-11
- 8.1.0 — 2022-11-12
- 8.0.4 — 2022-10-14
- 8.0.3 — 2022-10-14
- 8.0.2 — 2021-12-23
- 8.0.1 — 2021-11-24
- 8.0.0 — 2021-10-29
- 7.2.2 — 2021-10-16
- 7.2.1 — 2021-08-26
- … 4 more at https://npm.io/package/@nativescript/geolocation/versions

## README

# @nativescript/geolocation

## Contents
* [Intro](#intro)
* [Installation](#installation)
* [Android permissions requirements](#android-permissions-requirements)
* [iOS permissions requirements](#ios-permissions-requirements)
* [Use @nativescript/geolocation](#use-nativescriptgeolocation)
  * [Get current location](#get-current-location)
* [API](#api)
  * [Plugin functions](#plugin-functions)
  * [Location class](#location-class)
  * [Options interface](#options-interface)
* [Known Issues](#known-issues)
  * [Version conflicts with Google Play Services](#version-conflicts-with-google-play-services)
  * [openSettingsIfLocationHasBeenDenied on Android API level 30](#opensettingsiflocationhasbeendenied-on-android-api-level-30)

## Intro

A geolocation plugin to use for getting current location, monitor movement, etc.

## Installation

To install the plugin, run the following command in the  root  of your project.

```cli
npm install @nativescript/geolocation
```

## Android permissions requirements

To use geolocation on Android, you need to add the following permissions to your app's `AndroidManifest.xml` inside the `App_Resources/Android/src/main` directory:

```xml
  <!-- Always include this permission -->
  <!-- This permission is for "approximate" location data -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <!-- This permission is for "precise" location data -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
```

More information can be found in the [Android docs here](https://developer.android.com/training/location/permissions).

## iOS permissions requirements

If `iosAllowsBackgroundLocationUpdates` property of the [options](#options-interface) object is set to `true`, the following code is required in the `App_Resources/iOS/Info.plist` file:

```xml
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>
```

## Use @nativescript/geolocation

### Get current location

Before you call any method that gets the user's location, request for the user's permission by calling the `enableLocationRequest` method. Once the user has granted the permission, you can call the `getCurrentLocation()` method, passing it a [options](#options) object to get the user's current location.

```ts
import * as geolocation from '@nativescript/geolocation';
import { CoreTypes } from '@nativescript/core' // used to describe at what accuracy the location should get

geolocation.enableLocationRequest().then(() => {
    
    geolocation.getCurrentLocation({ desiredAccuracy: CoreTypes.Accuracy.high, maximumAge: 5000, timeout: 20000 }).then((currentLocation) => {

      console.log("My current latitude: ", currentLocation.latitude)
    })
  })
```

## API
### Plugin functions

The plugin provides the following functions for getting current location and more:

| Method  | Returns    | Description |
|---------|------------|-------------|
| `getCurrentLocation(options: Options)`                                                                   | Promise\<[Location](#location)\> | Gets current location applying the specified options (if any). Since version 5.0 of the plugin, it will use [requestLocation](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620548-requestlocation?language=objc) API for devices using `iOS 9.0+`. In situation of poor or no GPS signal, but available Wi-Fi it will take 10 sec to return the location.<br> The `options` parameter is optional. |
| `watchLocation(successCallback: successCallbackType, errorCallback: errorCallbackType, options?: Options)` | `number`              | Monitors location change.   |
| `watchPermissionStatus(permissionCallback: permissionCallbackType, errorCallback: errorCallbackType)`      | `number`              | (`iOS-only`)Monitors a change in location permission.|
| `clearWatch(watchId: number)` | `void` | Stops monitoring a change in location. The `watchId` parameter is returned from the `watchLocation()` method.  |
| `enableLocationRequest(always?: boolean, openSettingsIfLocationHasBeenDenied?: boolean`                   | `Promise<void> `    | Asks for permissions to use location services. On iOS if `always` is `true`, add the following keys to the `Info.plist`: [NSLocationAlwaysAndWhenInUseUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationalwaysandwheninuseusagedescription) (iOS 11.0+) OR [NSLocationAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationalwaysusagedescription?language=objc) (iOS 8.0-10.0) and [NSLocationWhenInUseUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationwheninuseusagedescription). Read more about [request always usage](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620551-requestalwaysauthorization). On Android `SDK >= 29`, the `always` parameter set to `true` requires the  `ACCESS_BACKGROUND_LOCATION` permission to be added to the `AndroidManifest.xml`. That results in the user getting a system dialog with the option `'allow all the time'` option. Read about Android location permissions [here](https://developer.android.com/training/location/permissions) and [here](https://developer.android.com/training/location/permissions#request-background-location). If `openSettingsIfLocationHasBeenDenied` is `true` and the permission has previously been denied then the Settings app will open so the user can change the location services permission. See the [exception](#android-api-level-30---opensettingsiflocationhasbeendenied) to this.|
|`isEnabled(options?: Options)` | `Promise<boolean>`  | Resolves `true` or `false` based on the location services availability. |
| `distance(loc1: Location, loc2: Location)`  | `number ` | Calculates the distance between two locations. Returns the distance in meters. |
| `getIOSLocationManagerStatus()`| [CLAuthorizationStatus](https://developer.apple.com/documentation/corelocation/clauthorizationstatus?language=objc)|  Returns the status of the Location Authorization permission.|

### Location class
 
 This is a data class that encapsulates the following common properties for a geolocation.


| Property           | Type | Description                                             |
| ------------------ |------|------------------------------------------------------- |
| `latitude`         | `number`| The latitude of the geolocation, in degrees.            |
| `longitude`        | `number`|  The longitude of the geolocation, in degrees.           |
| `altitude`         | `number`|  The altitude (if available), in meters above sea level. |
| `horizontalAccuracy` | `number`|  The horizontal accuracy, in meters.                     |
| `verticalAccuracy`   | `number`|  The vertical accuracy, in meters.                       |
| `speed`              | `number`|  The speed, in meters/second over ground.                |
| `timestamp`          | `Date`|  The time at which this location was determined.         |


### Options interface

The following are the properties of the options object that you pass to the geolocation [functions](#plugin-functions) of the plugin.

| Property | Type | Description
|:---------|:-----|:-----------
| `desiredAccuracy` | `CoreTypes.Accuracy` | _Optional_: Specifies if high accuracy or any is required. Defaults to `CoreTypes.Accuracy.high` which returns the finest location available but use more power than the `CoreTypes.Accuracy.any` option. `Accuracy.any` is considered to be about 100 meter accuracy.                                                               
| `updateDistance`                       | `number`     | _Optional_: Specifies how often to update the location. Update distance filter in meters. Read more in [Apple document](https://developer.apple.com/documentation/corelocation/cllocationmanager/1423500-distancefilter?language=objc) and/or [Google documents](<https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest.html#setSmallestDisplacement(float)>) |
| `updateTime`                            | `number`      | Interval between location updates, in milliseconds (ignored on iOS). Read more in [Google document](<https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest#setInterval(long)>).  Defaults to `1 minute`|
| `minimumUpdateTime`                     | `number` | _Optional_: Minimum time interval between location updates, in milliseconds (ignored on iOS). Read more in [Google document](<https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest#setFastestInterval(long)>).                                                                                                                                               |
| `maximumAge`                            | `number` | _Optional_: The maximum age of the location data, in `ms`. |
| `timeout`                               |  `number` | _Optional_: It indicates how long, in `ms`, to wait for a location. Defaults to `5 minutes`. |
| `iosAllowsBackgroundLocationUpdates`    | `boolean`         |_Optional_: Indicates whether to allow the application to receive location updates in the background (ignored on Android). Defaults to `false`. If enabled, the `UIBackgroundModes` key in `Info.plist` is required. A. Read more in [Apple document](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620568-allowsbackgroundlocationupdates?language=objc)                                                     |
| `iosPausesLocationUpdatesAutomatically` | `boolean`          | Indicates whether to allow the deactivation of the automatic pause of location updates (ignored on Android). Read more in [Apple document](https://developer.apple.com/documentation/corelocation/cllocationmanager/1620553-pauseslocationupdatesautomatical?language=objc)                                                                                                                                          |

## Breaking changes

- 9.0+:
  - `watchLocation` is now `async` in order to check for permissions before attempting to watch
## Known issues

### openSettingsIfLocationHasBeenDenied on Android API level 30

If the user declines the permission twice during the installation lifetime of the app on Android API level 30 , the user won't be taken to the settings even if the `openSettingsIfLocationHasBeenDenied` option is true for `enableLocationRequest()`.

## License

Apache License Version 2.0

---
_Source: https://npm.io/package/@nativescript/geolocation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._