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
Section titled “Filtering locations by mode”GET /v1/locations takes mode as a filter. It is a single value; send one
request per mode you need.
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
Section titled “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.
modeis always present on a location, unlikeactivity, which is omitted when the device has no reading.modeis computed when you read, from the storedactivity, so every stored location has one.- The list is closed today. Treat a mode you don’t recognise as
unknown.
Mode on trips
Section titled “Mode on trips”A trip has a mode and a mode_counts map:
mode_countscounts the trip’s locations per mode, leaving out modes with no locations. The counts add up topoint_count.modeis the moving mode (driving,cycling,running,walking) with the most locations. A tie goes to the faster mode, in that order. A trip is neverstill; with no moving locations its mode isunknown.