Compatibility API (/compat)#

Migration boundary: this callback API preserves the core community method shapes and numeric error contract. It does not install a navigator.geolocation global, and documented platform defaults or ignored options can differ. Review the matrix below before calling it drop-in for your application. New code should prefer the API.

#Import Path

// Import from /compat subpath
import Geolocation from 'react-native-nitro-geolocation/compat';

// Or named imports
import {
  getCurrentPosition,
  watchPosition,
  clearWatch,
} from 'react-native-nitro-geolocation/compat';

#Type imports

The /compat entry point is self-contained. Import the callback API contracts and every named supporting type from the same subpath:

import type {
  GeolocationConfiguration,
  GeolocationOptions,
  GeolocationOptionsWithMetadata,
  GeolocationResponse,
  GeolocationResponseWithMetadata,
  GeolocationError,
  GeolocationCoordinates,
  NullableDouble,
  AuthorizationLevel,
  LocationProvider,
  LocationProviderUsed,
  LocationAccuracyOptions,
  AndroidAccuracyPreset,
  IOSAccuracyPreset,
  IOSActivityType,
} from 'react-native-nitro-geolocation/compat';

No type import from the main package is required. TypeScript can resolve this subpath with node, node16, nodenext, and bundler module resolution.

#Compatibility Scope

This API is compatible with the core native @react-native-community/geolocation callback shape. It preserves the listed methods and numeric error contract for existing iOS and Android apps while the API gives new code a Promise/function API. The matrix is the compatibility boundary; options described as ignored/no-op and the missing global polyfill are intentional differences.

The package import and /compat subpath both support web by delegating to the browser navigator.geolocation API. The /compat web entry keeps the callback shape and legacy error constants, while setRNConfiguration() is a no-op and requestAuthorization() calls the success callback immediately because browsers do not expose a standalone geolocation authorization prompt.

#Summary

• setRNConfiguration
• requestAuthorization
• getCurrentPosition
• watchPosition
• Opt-in integrity metadata
• clearWatch
• stopObserving

#Details

#setRNConfiguration()

Preserves the legacy configuration API. Use it for iOS authorization/background settings. Android provider selection and request behavior should be configured per call or through the main package import.

Geolocation.setRNConfiguration(config: {
  skipPermissionRequests: boolean;
  authorizationLevel?: 'always' | 'whenInUse' | 'auto';
  enableBackgroundLocationUpdates?: boolean;
  locationProvider?: 'playServices' | 'android' | 'auto';
});

Supported options:

• skipPermissionRequests (boolean) - Required by the public type. Pass false for legacy compatibility, or true when you request permissions yourself before using Geolocation APIs. For deterministic app flows, request permissions explicitly before calling location APIs.
• authorizationLevel (string, iOS-only) - Either "whenInUse", "always", or "auto". Changes whether the user will be asked to give "always" or "when in use" location services permission. Any other value or auto will use the default behaviour, where the permission level is based on the contents of your Info.plist.
• enableBackgroundLocationUpdates (boolean, iOS-only) - When using skipPermissionRequests, toggles whether to enable Core Location background updates. Defaults to false unless explicitly set.
• locationProvider (string, Android-only) - Either "playServices", "android", or "auto". Preserved for API compatibility on /compat; use the main package import when you need Android fused/provider selection.

#requestAuthorization()

Request suitable Location permission.

Geolocation.requestAuthorization(
  success?: () => void,
  error?: (error: {
    code: number;
    message: string;
    PERMISSION_DENIED: number;
    POSITION_UNAVAILABLE: number;
    TIMEOUT: number;
  }) => void
);

On iOS if NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

#getCurrentPosition()

Invokes the success callback once with the latest location info.

Geolocation.getCurrentPosition(
  success: (position: {
    coords: {
      latitude: number;
      longitude: number;
      altitude: number | null;
      accuracy: number;
      altitudeAccuracy: number | null;
      heading: number | null;
      speed: number | null;
    };
    timestamp: number;
  }) => void,
  error?: (error: {
    code: number;
    message: string;
    PERMISSION_DENIED: number;
    POSITION_UNAVAILABLE: number;
    TIMEOUT: number;
  }) => void,
  options?: {
    timeout?: number;
    maximumAge?: number;
    enableHighAccuracy?: boolean;
    accuracy?: {
      android?: 'high' | 'balanced' | 'low' | 'passive';
      ios?: 'bestForNavigation' | 'best' | 'nearestTenMeters' | 'hundredMeters' | 'kilometer' | 'threeKilometers' | 'reduced';
    };
    activityType?: 'other' | 'automotiveNavigation' | 'fitness' | 'otherNavigation' | 'airborne';
    pausesLocationUpdatesAutomatically?: boolean;
    showsBackgroundLocationIndicator?: boolean;
    includeExtraMetadata?: boolean;
  }
);

Supported options:

• timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Native compat defaults to 10 minutes. Web omits the field when you do not pass it, so browser defaults apply.
• maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. Native compat defaults to INFINITY. Web omits the field when you do not pass it, so browser defaults apply.
• enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
• accuracy - Native-only platform-specific accuracy preset. On iOS and Android, it takes precedence over enableHighAccuracy when supplied for the current platform. On web, /compat forwards only enableHighAccuracy, timeout, and maximumAge to navigator.geolocation.
• activityType (iOS only) - Core Location activity type.
• pausesLocationUpdatesAutomatically (iOS only) - Core Location automatic pause behavior.
• showsBackgroundLocationIndicator (iOS only) - Shows the iOS background location indicator when the app has background location capability and permission.
• includeExtraMetadata - Set to true to opt this call into the metadata response described in Opt-in integrity metadata. Omit it or pass false to keep the exact community response shape. This JS-only flag is not forwarded to the native location request.

#watchPosition()

Invokes the success callback whenever the location changes. Returns a watchId (number).

Geolocation.watchPosition(
  success: (position: {
    coords: {
      latitude: number;
      longitude: number;
      altitude: number | null;
      accuracy: number;
      altitudeAccuracy: number | null;
      heading: number | null;
      speed: number | null;
    };
    timestamp: number;
  }) => void,
  error?: (error: {
    code: number;
    message: string;
    PERMISSION_DENIED: number;
    POSITION_UNAVAILABLE: number;
    TIMEOUT: number;
  }) => void,
  options?: {
    interval?: number;
    fastestInterval?: number;
    timeout?: number;
    maximumAge?: number;
    enableHighAccuracy?: boolean;
    accuracy?: {
      android?: 'high' | 'balanced' | 'low' | 'passive';
      ios?: 'bestForNavigation' | 'best' | 'nearestTenMeters' | 'hundredMeters' | 'kilometer' | 'threeKilometers' | 'reduced';
    };
    distanceFilter?: number;
    useSignificantChanges?: boolean;
    activityType?: 'other' | 'automotiveNavigation' | 'fitness' | 'otherNavigation' | 'airborne';
    pausesLocationUpdatesAutomatically?: boolean;
    showsBackgroundLocationIndicator?: boolean;
    includeExtraMetadata?: boolean;
  }
) => number;

Supported options:

• interval (ms) -- (Android only) The rate in milliseconds at which your app prefers to receive location updates. Note that the location updates may be somewhat faster or slower than this rate to optimize for battery usage, or there may be no updates at all (if the device has no connectivity, for example).
• enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
• accuracy - Native-only platform-specific accuracy preset. On iOS and Android, it takes precedence over enableHighAccuracy when supplied for the current platform. On web, /compat forwards only enableHighAccuracy, timeout, and maximumAge to navigator.geolocation.
• distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m on Android and no distance filter on iOS.
• useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.
• activityType (iOS only) - Core Location activity type.
• pausesLocationUpdatesAutomatically (iOS only) - Core Location automatic pause behavior.
• showsBackgroundLocationIndicator (iOS only) - Shows the iOS background location indicator when the app has background location capability and permission.
• includeExtraMetadata - Set to true to opt this watch subscription into the metadata response described below. Other watches, including concurrent default watches, keep the exact community response shape.

timeout, maximumAge, and fastestInterval are part of the legacy option type for compatibility, but native /compat watches do not use them. On web, watchPosition() forwards timeout, maximumAge, and enableHighAccuracy to navigator.geolocation.

#Opt-in integrity metadata

The default /compat response remains exactly { coords, timestamp } in both TypeScript and at runtime. Existing callers do not receive extra own-properties, including properties whose value would be undefined.

New callers can request mock/provider metadata for one current-position call or one watch subscription:

import Geolocation from 'react-native-nitro-geolocation/compat';
import type {
  GeolocationOptionsWithMetadata,
  GeolocationResponseWithMetadata,
} from 'react-native-nitro-geolocation/compat';

const options: GeolocationOptionsWithMetadata = {
  includeExtraMetadata: true,
  enableHighAccuracy: true,
};

Geolocation.getCurrentPosition(
  (position: GeolocationResponseWithMetadata) => {
    if (position.mocked === true) {
      console.warn('The platform marked this sample as simulated');
    }

    console.log(position.provider);
  },
  undefined,
  options,
);

The opt-in response adds:

• mocked?: boolean - true or false only when the platform reports the value. Absence means unknown; it must not be treated as false. Android uses the platform mock-location marker. iOS uses CLLocation.sourceInformation on iOS 15 and newer when it is present.
• provider?: 'fused' | 'gps' | 'network' | 'passive' | 'unknown' - The native provider where it can be identified. iOS and web report unknown.

The option is per call/subscription rather than global. A default watch and an opted-in watch can run concurrently without changing each other's response shape. Native apps must rebuild after upgrading because the opted-in path uses new native methods. If newer JavaScript is delivered OTA to an older native binary, the option safely falls back to the default { coords, timestamp } shape. Gate any code that requires metadata on rollout of the matching native binary; the metadata fields remain optional for this reason. On web, mocked is omitted because browser geolocation does not expose that signal, and provider is unknown.

#clearWatch()

Clears watch observer by id returned by watchPosition()

Geolocation.clearWatch(watchID: number);