Location

session.location reports the phone’s GPS position. Get a single fix with getOnce(), or subscribe to a stream with onUpdate().

src/background/index.ts

const fix = await session.location.getOnce();
session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: `${fix.lat.toFixed(4)}, ${fix.lng.toFixed(4)}`}]);

Location needs the LOCATION permission in your manifest. Without it, the phone rejects both paths with PERMISSION_NOT_DECLARED and no reading arrives.

A single fix

getOnce() resolves with the next available reading from the phone. Use it at app load to seed your UI before a stream starts.

const fix = await session.location.getOnce();

It returns a Promise<LocationData>.

Continuous updates

onUpdate() delivers a LocationData every time the position changes. It returns an unsubscribe function.

const off = session.location.onUpdate((data) => {
  session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: `${data.lat}, ${data.lng}`}]);
});

off(); // stop receiving updates

LocationData

Both paths hand you the same shape:

Field	Type	Notes
`lat`	`number`	Latitude in degrees.
`lng`	`number`	Longitude in degrees.
`accuracy`	`number?`	Accuracy in meters, when the platform reports it.
`timestamp`	`number?`	Unix ms timestamp of the fix.
`correlationId`	`string?`	Set when the event answers a single-location request.

Permission

session.location.hasPermission is true when LOCATION is declared in your manifest. It reports the manifest declaration, not the OS grant: if the user denied the system location prompt, getOnce() and onUpdate() produce no reading. See Permissions.

LOCATION and BACKGROUND_LOCATION are separate manifest keys, and hasPermission checks for LOCATION only. For turn-by-turn directions built on position, see session.navigation.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

A single fix

Continuous updates

LocationData

Permission

​A single fix

​Continuous updates

​LocationData

​Permission

A single fix

Continuous updates

LocationData

Permission