> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Location and timezone

> Read and set the GPS location and timezone a Lusor Phone reports to apps.

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

```bash theme={null}
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`. |

```bash cURL theme={null}
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" }'
```

```python Python theme={null}
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())
```

```javascript Node.js theme={null}
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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.