Location and timezone

A Lusor Phone reports a GPS location and a timezone to the apps on it. By default both follow the phone’s Internet exit IP. You can set your own values instead. These routes work on Lusor Phones on the Phone plan only. Any other phone returns 409 not_managed_phone.

Modes

`mode`	Where the location and timezone come from
`auto`	The phone’s Internet exit IP. They are applied again after every IP change.
`override`	The values you set with `PUT …/geo`. They stay through restarts and IP changes until you clear them, or until the phone is wiped or removed.

An override can disagree with the exit IP’s country or timezone. That is allowed.

Read the setting

curl https://api.lusor.ai/v1/workspaces/$WS/devices/$DEVICE/geo \
  -H "X-Api-Key: $LUSOR_API_KEY"

Field	Meaning
`mode`	`auto` or `override`.
`latitude`, `longitude`	The location the phone was last given. `null` when none is known yet.
`timezone`	An IANA zone name such as `Europe/Paris`.
`apply`	Override mode only, otherwise `null`. Whether the phone has the override yet.

apply.state is one of:

`state`	Meaning
`pending`	Stored, not yet given to the phone.
`applied`	The phone has it.
`held`	Waiting, with a `reason`. `lifecycle` means the phone is restarting or resetting, and the override is applied when that finishes.
`failed`	The phone did not take it. `error` is `geo_apply_failed`. Send the `PUT` again to retry.

Set a location

PUT …/geo with all three fields:

Field	Meaning
`latitude`	-90 to 90 degrees. Stored to six decimals.
`longitude`	-180 to 180 degrees. Stored to six decimals.
`timezone`	An IANA zone name, for example `Europe/Paris`.

curl -X PUT https://api.lusor.ai/v1/workspaces/$WS/devices/$DEVICE/geo \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "latitude": 48.8566, "longitude": 2.3522, "timezone": "Europe/Paris" }'

import os, requests

URL = f"https://api.lusor.ai/v1/workspaces/{os.environ['WS']}/devices/{os.environ['DEVICE']}/geo"
H = {"X-Api-Key": os.environ["LUSOR_API_KEY"]}

r = requests.put(URL, headers=H, json={
    "latitude": 48.8566, "longitude": 2.3522, "timezone": "Europe/Paris",
})
print(r.status_code, r.json())

const URL = `https://api.lusor.ai/v1/workspaces/${process.env.WS}/devices/${process.env.DEVICE}/geo`;

const r = await fetch(URL, {
  method: "PUT",
  headers: { "X-Api-Key": process.env.LUSOR_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ latitude: 48.8566, longitude: 2.3522, timezone: "Europe/Paris" }),
});
console.log(r.status, await r.json());

The change is stored at once and given to the phone in the background, usually within a minute. Read apply.state with GET …/geo to see when it lands. An API key can set and clear the location on its own workspace. In the app, admins and members can.

Go back to automatic

DELETE …/geo clears the override. The location and timezone follow the exit IP again and are applied now. Clearing when nothing is set changes nothing.

Errors

Status	`error`	Meaning
`400`	`geo_override_invalid`	A latitude, longitude or timezone is out of range, or the timezone is not an IANA zone name.
`409`	`not_managed_phone`	Not a Lusor Phone on the Phone plan.
`409`	`phone_busy`	The phone is restarting or resetting. Try again when it is ready.
`409`	`phone_not_ready`	The phone is not set up yet, or has been removed.
`504`	`geo_change_queued`	Another operation on the phone is running. Your change is queued and still applies. Read it back with `GET …/geo`.

Get started

Agents & sessions

Phones

Billing and limits

Location and timezone

Modes

Read the setting

Set a location

Go back to automatic

Errors

​Modes

​Read the setting

​Set a location

​Go back to automatic

​Errors

Modes

Read the setting

Set a location

Go back to automatic

Errors