Data types

Every type below is a named export re-exported from the package root, so you can import them directly for your own function signatures and component props:

import type { Location, State, Geofence } from '@dc-bgeo/react-native-background-geolocation';

Only the fields the app (and its backend) actually rely on are typed strictly here. A few object-shaped config and options types carry a permissive [key: string]: any index signature — unknown keys pass through uninterpreted rather than causing a type error.

Location & sensors

Location

The core location record. It’s the payload of onLocation and (when a fix exists) onMotionChange and onHeartbeat; the resolved value of getCurrentPosition(), watchPosition(), setOdometer()/resetOdometer(), and sync()/getLocations(); and the accepted shape for insertLocation() (as a Partial<Location>).

Field	Type	Description
uuid	string	Unique record id.
timestamp	string	ISO-8601 UTC.
age	number	Optional. Fix age in milliseconds at the time it was processed.
odometer	number	Cumulative odometer reading, metres.
coords	Coords	Position/motion fields.
activity	MotionActivity	Classified motion activity at the time of the fix.
battery	Battery	Device battery snapshot.
is_moving	boolean | null	Motion-state machine’s verdict at the time of this fix. null while a cold-started session’s first fixes are still in the unconfirmed-MOVING probing window — up to stopTimeout minutes after start(). The engine emits null there by design, so a server falls back to coords.speed instead of trusting a phantom “started moving”. Treat null the same as false.
sample	boolean	Optional. true when this Location was resolved by getCurrentPosition() — either an existing fix served for a fresh-enough maximumAge, or the best (most accurate) of several fixes sampled internally — rather than delivered by the ambient tracking stream. The intermediate fixes collected while sampling for the best one are never themselves surfaced as separate Location records. Also true on the fix resolved by setOdometer()/resetOdometer() — that fix carries event: 'odometer' (see the event field below) rather than coming from getCurrentPosition().
event	string	Optional. Tags why this record was produced when it isn’t a plain tracked fix. Observed values: 'motionchange' (the record captured just before entering the stationary state) and 'odometer' (the fix resolved by setOdometer()/resetOdometer()).
extras	object	Optional passthrough — e.g. { watch: true } on watchPosition() fixes, { heartBeat: true }, { getCurrentPosition: true }. Config-level extras form the base of every record; per-call extras are layered on top.

Snake_case: is_moving mirrors the wire format the native engines emit (camelCase elsewhere in this type, but this one field is snake_case — see also Coords and Battery below, which are almost entirely snake_case).

Coords

Nested inside Location.coords.

Field	Type	Description
latitude	number	Degrees.
longitude	number	Degrees.
accuracy	number	Horizontal accuracy, metres.
altitude	number	Optional. Metres above sea level.
altitude_accuracy	number	Optional. Vertical accuracy, metres.
speed	number	Optional. Metres/second.
speed_accuracy	number	Optional. Metres/second.
heading	number	Optional. Degrees.
heading_accuracy	number	Optional. Degrees.
ellipsoidal_altitude	number	Optional. Metres, WGS84 ellipsoidal (as opposed to altitude, which is mean-sea-level/geoid-based).

Snake_case: altitude_accuracy, speed_accuracy, heading_accuracy, and ellipsoidal_altitude are snake_case — they mirror the wire format the native engines emit, unlike latitude/longitude/accuracy/altitude/speed/heading.

MotionActivity

Nested inside Location.activity. Its type values are also the vocabulary accepted by config.triggerActivities (a CSV of these same strings).

Field	Type	Description
type	'still' | 'on_foot' | 'walking' | 'running' | 'on_bicycle' | 'in_vehicle' | 'unknown'	Classified activity.
confidence	number	Classifier confidence for type.

Snake_case: the field names (type, confidence) are plain camelCase, but three of the type enum values themselves — on_foot, on_bicycle, in_vehicle — are snake_case, again mirroring the native wire format.

Battery

Nested inside Location.battery.

Field	Type	Description
level	number	Battery level, 0.0–1.0.
is_charging	boolean	Whether the device is currently charging.

Snake_case: is_charging mirrors the native wire format.

State

The tracker’s state snapshot: resolved by ready(), setConfig(), start(), stop(), and getState(). Every field past enabled is optional — State documents the superset of health/diagnostic fields either native engine may populate, not a fixed cross-platform guarantee, and the type’s own index signature ([key: string]: any) admits further engine-specific fields not listed here.

Field	Type	Description
enabled	boolean	Whether tracking is enabled (the persisted on/off intent).
trackingActive	boolean	Optional. Whether the tracking engine currently has an active location request outstanding.
authorization	number	Optional. One of the AUTHORIZATION_STATUS_* constants.
lastRawFixAge	number | null	Optional, nullable. Diagnostic: age of the last raw fix (before filtering), in seconds. null until one arrives.
lastAcceptedFixAge	number | null	Optional, nullable. Diagnostic: age of the last accepted fix (after filtering), in seconds. null until one arrives.
lastLocationError	string | null	Optional, nullable. Diagnostic: the most recent location error message.
locationFailureCount	number	Optional. Diagnostic counter.
backgroundRearmCount	number	Optional. Diagnostic counter.
watchdogRecoveryCount	number	Optional. Diagnostic counter.
wakeRearmCount	number	Optional. Diagnostic counter.
stationaryRegionArmed	boolean	Optional. Diagnostic.
monitoredWakeRegions	number	Optional. Diagnostic counter.
lastWakeError	string | null	Optional, nullable. Diagnostic: the most recent wake-region error message.
trackingMode	number	Optional. Diagnostic.
isMoving	boolean	Optional. Current motion-state-machine verdict — same value as onMotionChange’s isMoving.
schedulerEnabled	boolean	Optional. Diagnostic.
odometer	number	Optional. Cumulative odometer reading, metres.
geofenceCount	number	Optional. Diagnostic counter.
lastGeofenceError	string | null	Optional, nullable. Diagnostic: the most recent geofence-registration error message.
connected	boolean	Optional. Validated-internet connectivity — see ConnectivityChangeEvent.

Events

ProviderChangeEvent

Payload of onProviderChange and the resolved value of getProviderState() (same shape).

Field	Type	Description
status	number	One of the AUTHORIZATION_STATUS_* constants — 3 is Always.
enabled	boolean	Whether location services are on at all.
gps	boolean	GPS provider enabled.
network	boolean	Network provider enabled.
accuracyAuthorization	number	Optional, iOS only — ACCURACY_AUTHORIZATION_FULL/REDUCED.

MotionChangeEvent

Payload of onMotionChange.

Field	Type	Description
isMoving	boolean	true on the moving transition, false on the stationary transition.
location	Location	Optional (location?: Location | null) — absent (Android) or null (iOS) on the very first motionchange of a tracking session, before any fix exists yet (the initial probe fires from start() ahead of any location). Guard before dereferencing — see the Events reference for the same caveat.

GeofenceEvent

Payload of onGeofence.

Field	Type	Description
identifier	string	The geofence’s identifier.
action	'ENTER' | 'EXIT' | 'DWELL'	The transition type.
location	Location	The fix that triggered the transition.
extras	object	Optional. The geofence’s own extras, echoed back.

GeofencesChangeEvent

Payload of onGeofencesChange — a delta of the OS-registered subset, not the full persisted set (see Geofence below and the Geofencing guide).

Field	Type	Description
on	Geofence[]	Geofences newly registered with the OS.
off	Geofence[]	Geofences just unregistered.

HttpEvent

Payload of onHttp — fired once per completed location-sync HTTP request (log uploads do not emit this event; see the logging guide).

Field	Type	Description
success	boolean	true when status is 2xx.
status	number	HTTP status code; 0 when the request never got a response (network error).
responseText	string	Response body (or the error message when status is 0), truncated to 1024 characters.

ConnectivityChangeEvent

Payload of onConnectivityChange. Fired on validated-internet transitions (Android NET_CAPABILITY_VALIDATED / iOS NWPath.satisfied — a captive-portal Wi-Fi network reports false); a newly-registered listener also immediately receives the current state as a synthetic first delivery.

Field	Type	Description
connected	boolean	Validated-internet reachability.

Geofencing

Geofence

A persisted geofence definition — the shape accepted by addGeofence()/addGeofences() and returned by getGeofences() and the on/off arrays of GeofencesChangeEvent. See the Geofencing guide for validation rules, proximity slicing, and DWELL semantics.

Field	Type	Description
identifier	string	Unique geofence id.
radius	number	Metres.
latitude	number	Degrees.
longitude	number	Degrees.
notifyOnEntry	boolean	Optional.
notifyOnExit	boolean	Optional.
notifyOnDwell	boolean	Optional.
loiteringDelay	number	Optional. Milliseconds; required alongside notifyOnDwell for a DWELL transition.
extras	object	Optional. Echoed back on the corresponding GeofenceEvent.

Positioning options

CurrentPositionOptions

Parameter of getCurrentPosition().

Field	Type	Description
persist	boolean	Optional. Whether the resolved fix is added to the upload queue like a normal tracked point.
samples	number	Optional. Number of fixes to sample before returning the best (most accurate) one.
timeout	number	Optional. Seconds to wait before giving up. Default 30.
maximumAge	number	Optional. Accept a cached fix up to this many milliseconds old instead of sampling a new one.
desiredAccuracy	number	Optional. One of the DESIRED_ACCURACY_* constants.
extras	object	Optional. Merged into the returned location’s extras.

WatchPositionOptions

Parameter of watchPosition().

Field	Type	Description
interval	number	Optional. Desired update interval, milliseconds.
desiredAccuracy	number	Optional. One of the DESIRED_ACCURACY_* constants.
persist	boolean	Optional. Whether fixes are added to the upload queue.
extras	object	Optional. Merged into each returned location’s extras.

Logging

LogEntry

Resolved array-element type of getLog(); written by logger.error/warn/info/debug/verbose and the native engine itself. See the logging guide for retention and upload cadence.

Field	Type	Description
ts	string	ISO-8601 UTC.
level	number	1=ERROR, 2=WARN, 3=INFO, 4=DEBUG, 5=VERBOSE.
src	'native' | 'js'	Whether the line originated in the native engine or app-side JS (logger.* calls).
event	string	Short event tag.
message	string	Optional. Human-readable log line.
data	any	Optional. JSON-serialized data attached to the line.

Headless

HeadlessEvent

Parameter of the task passed to registerHeadlessTask() Android . Unlike every other event type on this page, there is no params/payload wrapper — the event’s payload fields are flattened alongside name directly on the same object (enforced by the type’s [key: string]: any index signature). iOS never invokes a registered headless task at all, since there’s no AppRegistry-driven headless service on that platform — see registerHeadlessTask() and the boot & killed-app guide.

Field	Type	Description
name	'heartbeat' | 'motionchange' | 'geofence' | 'providerchange' | 'powersavechange' | 'http' | 'connectivitychange'	The event type. The union matches the Android engine’s headless dispatch set exactly; 'location' is deliberately not part of it — see below.
[key: string]	any	The rest of the event’s fields, flattened alongside name — e.g. a headless motionchange carries isMoving/location directly on this object, not nested under a params key.

No headless location: the Android engine never dispatches a location event headlessly, and the union reflects that — the runtime set of headless-dispatched event names is exactly heartbeat, motionchange, geofence, providerchange, powersavechange, http, and connectivitychange, so narrowing on event.name is exhaustive. High-frequency location fixes are deliberately excluded to avoid spinning up Android’s HeadlessJsTaskService (and a wakelock) per fix while tracking, which would drain battery and risk ANRs/foreground-service-start restrictions; fixes taken while the JS context isn’t running are still durably queued and uploaded natively. This mirrors the same note under onLocation on the Events reference.

Subscriptions

Subscription

Returned by every on* listener method on the Events reference.

Field	Type	Description
remove	() => void	Detaches this one listener. To tear down every listener at once, call removeListeners() instead.