Getting Node Location with location.get

I have spent plenty of time fighting with device location permissions. It usually starts with a simple request and ends with me chasing down background execution rules or wondering why I am getting coarse data when I need GPS coordinates. It is a common frustration when you want your nodes to be context-aware without writing custom boilerplate for every OS.

I want to show you how to handle this using node commands. Instead of managing complex OS listeners, you can use a single command to get the data you need from any connected node.

What You’ll Need

• A node device (macOS, iOS, or Android).
• CLI access to your gateway.

Quick Start

The location.get command is off by default. You need to configure the node settings before you can pull coordinates.

1. Set the Location Mode

Each node has a location.enabledMode setting. I recommend choosing the level that fits your specific needs:

• off: Disables all location sharing.
• whileUsing: Only allows location access when the app is open.
• always: Allows background location (requires specific OS permissions).

2. Enable Precise Location

If you need exact GPS data, set location.preciseEnabled to true. If this is off, the node shares approximate location to save battery or maintain privacy.

3. Run the Command via CLI

You can test this immediately using the CLI. Run this command:

openclaw nodes location get --node <id>

4. Use the API

For programmatic access, use node.invoke. Here is how you structure the request:

Request Params:

{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

Response Payload:

{
  "lat": 48.20849,
  "lon": 16.37208,
  "accuracyMeters": 12.5,
  "altitudeMeters": 182.0,
  "speedMps": 0.0,
  "headingDeg": 270.0,
  "timestamp": "2026-01-03T12:34:56.000Z",
  "isPrecise": true,
  "source": "gps|wifi|cell|unknown"
}

Troubleshooting

If the command fails, check the error code in the response. I usually see these four issues:

• LOCATION_DISABLED: The selector in the node settings is set to “off.”
• LOCATION_PERMISSION_REQUIRED: The OS is missing the permission for the mode you requested.
• LOCATION_BACKGROUND_UNAVAILABLE: The app is in the background, but the node is only set to “While Using.”
• LOCATION_TIMEOUT: The device could not get a location fix within your timeoutMs limit.

If you see LOCATION_UNAVAILABLE, it typically means a system-level failure or that the device has no available location providers.

For more help with your specific setup, check out the AI Setup Assistant.

What’s Next

• Node Permissions Overview
• Using node.invoke