# Location mode

> The normalised movement mode on every location and trip — still, walking, running, cycling, driving or unknown — how it is derived from the device's activity, and how to filter on it.

Source: https://docs.getbeekon.com/api/location-mode/

Every location carries a **`mode`**: a normalised word for how the device was moving when it recorded the fix. Trips use the same vocabulary for their overall `mode`. It is derived on the server from the location’s raw `activity` reading, so it needs no SDK change. The SDK records `activity`; the server normalises it to one of the six `mode` values below; the console shows the result as **Travel mode**.

## Filtering locations by mode

[`GET /v1/locations`](https://docs.getbeekon.com/api/locations/) takes `mode` as a filter. It is a single value; send one request per mode you need.

```sh
curl -s -G https://api.in1.getbeekon.com/v1/locations \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  --data-urlencode "from=2026-10-06T00:00:00Z" \
  --data-urlencode "to=2026-10-07T00:00:00Z" \
  --data-urlencode "mode=driving"
```

Like `install_id`, `user_id` and `gate_reason`, `mode` is a selective filter: with it, the window may be at most 24 hours (`400 window_too_large` otherwise). A value that is not one of the six modes, an empty value, a comma-separated list or a repeated `mode` is `400 invalid_mode`. `mode=unknown` matches locations with no activity reading as well as unrecognised ones.

## The six modes

| `mode`    | Derived from `activity`                                                      |
| --------- | ---------------------------------------------------------------------------- |
| `driving` | `automotive`                                                                 |
| `cycling` | `cycling`                                                                    |
| `running` | `running`                                                                    |
| `walking` | `walking`                                                                    |
| `still`   | `stationary`                                                                 |
| `unknown` | anything else: no `activity`, the literal `unknown`, or a value no SDK sends |

The mapping is exact: values are not case-folded, so `Walking` is `unknown`.

* `mode` is **always present** on a location, unlike `activity`, which is omitted when the device has no reading.
* `mode` is computed when you read, from the stored `activity`, so every stored location has one.
* The list is closed today. Treat a mode you don’t recognise as `unknown`.

Activity detection is off by default

Devices report `activity` only when activity detection is on (`tracking.detect_activity` in your [remote config](https://docs.getbeekon.com/api/remote-config/), default `false`). With it off, every location’s mode, and every trip’s, is `unknown`. That is expected, not an error.

## Mode on trips

A [trip](https://docs.getbeekon.com/api/trips/) has a `mode` and a `mode_counts` map:

* `mode_counts` counts the trip’s locations per mode, leaving out modes with no locations. The counts add up to `point_count`.
* `mode` is the **moving** mode (`driving`, `cycling`, `running`, `walking`) with the most locations. A tie goes to the faster mode, in that order. A trip is never `still`; with no moving locations its mode is `unknown`.
