elizaos--eliza/plugins/plugin-native-location/README.md

@elizaos/capacitor-location

Capacitor plugin for geolocation within elizaOS apps. Provides current position, continuous location watching, and permission management across browser, iOS, and Android.

Capabilities

• Get current position — one-shot GPS/network fix with configurable accuracy and timeout
• Watch position — continuous location stream with distance and interval throttling
• Permission management — check and request OS location permissions
• Cross-platform — identical TypeScript API on web (Geolocation API), iOS (CoreLocation), and Android (FusedLocationProviderClient)

Installation

npm install @elizaos/capacitor-location
npx cap sync

Usage

import { Location } from '@elizaos/capacitor-location';

// Get current position
const result = await Location.getCurrentPosition({ accuracy: 'high', timeout: 10000 });
console.log(result.coords.latitude, result.coords.longitude);

// Watch position changes
const { watchId } = await Location.watchPosition({ accuracy: 'high', minDistance: 10 });
await Location.addListener('locationChange', (location) => {
  console.log('New position:', location.coords);
});

// Stop watching
await Location.clearWatch({ watchId });

// Permissions
const status = await Location.checkPermissions();
if (status.location !== 'granted') {
  await Location.requestPermissions();
}

API

getCurrentPosition(options?)

Returns a single LocationResult with the device's current coordinates.

Options:

Option	Type	Default	Description
accuracy	"best"|"high"|"medium"|"low"|"passive"	"high"	Desired fix accuracy
maxAge	number (ms)	0	Return cached location if younger than this
timeout	number (ms)	10000	Abort if no fix within this window

watchPosition(options?)

Starts continuous location updates. Returns { watchId: string }. Location updates are delivered via the locationChange event. Stop with clearWatch.

Additional options beyond getCurrentPosition:

Option	Type	Default	Description
minDistance	number (m)	0	Minimum movement before firing an update
minInterval	number (ms)	0	Minimum time between updates

clearWatch({ watchId })

Stops a running watch by its ID.

checkPermissions()

Returns LocationPermissionStatus without prompting. Fields: location and background (iOS/Android only), each "granted" | "denied" | "prompt".

requestPermissions()

Requests OS location permission. On web, this implicitly triggers a getCurrentPosition call (the only way browsers expose the permission prompt).

Events

Event	Payload	Description
locationChange	LocationResult	Fired on each position update while watching
error	LocationErrorEvent	Fired on location errors

LocationErrorEvent.code values: PERMISSION_DENIED, POSITION_UNAVAILABLE, TIMEOUT, UNKNOWN.

Platform setup

iOS

Add to Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses your location to …</string>

<!-- Only if requesting "always" permission -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app uses your location in the background to …</string>

Minimum deployment target: iOS 13.0.

Android

Add to AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Only if background location is needed -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Requires Google Play Services (com.google.android.gms:play-services-location).

Building

bun run build        # tsc + rollup
bun run build:docs   # regenerate README from JSDoc, then build
bun run clean        # remove dist/