@capacitor/geolocation
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    @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);
    };

    API

    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) => 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 PositionOptions
    callback WatchPositionCallback

    Returns: Promise<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'

    Install

    npm i @capacitor/[email protected]

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    65 kB

    Total Files

    28

    Last publish

    Collaborators

    • ionicjs
    • maxlynch
    • mhartington
    • jcesarmobile
    • cmapoole
    • nhyatt
    • elylucas