Skip to content

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.

GET /v1/locations takes mode as a filter. It is a single value; send one request per mode you need.

Terminal window
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.

modeDerived from activity
drivingautomotive
cyclingcycling
runningrunning
walkingwalking
stillstationary
unknownanything 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.

A trip 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.