Skip to content

Locations

GET /v1/locations reads the locations your devices uploaded, for a time window, in the order the devices recorded them. Locations the server judged unusable (mock locations, poor accuracy, impossible speed) are stored too and can be read on request, each with the reason. To keep a copy of every location as it arrives, read GET /v1/locations/feed instead.

Scope: locations:read

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 "limit=100"

All parameters ride the query string. Parameters this endpoint does not define are ignored. A defined parameter sent twice is a 400 with that parameter’s error, and an empty value is a 400 — except limit= and cursor=, which count as absent.

ParameterRequiredMeaning
fromyesInclusive start of the window, on the device’s recorded time.
toyesExclusive end of the window. Must be after from.
install_idnoOnly this device. Max 128 bytes; must not be blank or contain a NUL character.
user_idnoOnly locations recorded under this user id (the value your app set in the SDK). Max 256 bytes, valid UTF-8, no control characters. Matched exactly, with no trimming.
include_gatednotrue to include locations the server gated, alongside admitted ones. false (the default) returns admitted locations only. Exactly true or false, lowercase.
gate_reasonnoOnly locations gated for this reason: low_accuracy, implausible_speed or mock. Cannot be combined with include_gated.
modenoOnly locations with this movement mode: still, walking, running, cycling, driving or unknown. One value; a list is refused.
ordernoasc (the default): oldest first. desc: newest first — the latest locations of a long window in one request. Exactly asc or desc, lowercase. See Newest first.
limitno1–500, default 100. See Pagination.
cursornoThe previous page’s next_cursor.

The window. from and to are RFC 3339 timestamps with any offset — 2026-10-07T15:00:00+05:30 and 2026-10-07T09:30:00Z are the same instant. A bare date (2026-10-07) is refused, never read as midnight. The window is half-open: a location recorded exactly at from is included and one exactly at to is not, so consecutive windows ([a, b), [b, c)) tile with no overlap and no gap.

Filters combine with AND. install_id=X&user_id=Y returns locations from device X recorded under user Y.

install_id, user_id, gate_reason and mode are selective filters. When any of them is present, to − from must be at most 24 hours (exactly 24 hours is allowed), or the request is 400 window_too_large — the window is never silently narrowed. To read a longer period for one device, walk consecutive 24-hour windows. A read without those filters has no maximum window.

{
"locations": [
{
"id": "01900100-0000-7000-8000-000000000001",
"accuracy_m": 12.5,
"activity": "walking",
"altitude_m": 920.25,
"battery_percent": 63,
"bearing_deg": 271.5,
"device": {
"install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
"session_id": "sess-1",
"user_id": "acct_9931"
},
"extras": {"fleet": "north", "route": "R-12"},
"is_charging": true,
"is_mock": false,
"latitude": 12.9716,
"longitude": 77.5946,
"mode": "walking",
"motion": "moving",
"power_save_mode": false,
"received_at": "2026-08-06T07:06:45.000Z",
"recorded_at": "2026-08-06T07:06:41.000Z",
"source": "sdk",
"speed_mps": 1.4,
"trigger": "check_in",
"trust_tier": "unverified"
}
],
"next_cursor": null,
"retention_floor": null,
"schema_version": 1
}

(Pretty-printed here; the API sends compact JSON.)

MemberTypeMeaning
locationsarrayThe locations, ordered by recorded_at ascending (ties broken by id), or descending with order=desc. [] when empty.
next_cursorstring | nullThe cursor for the next page, or null when the window is exhausted.
retention_floorstring | nullThe earliest instant your project’s data is still kept from, or null if nothing has ever been deleted under retention. See Retention.
schema_versioninteger1.
FieldTypePresenceMeaning
idstringalwaysThe location’s id, minted by the device: a lowercase UUID of any version. Unique only together with recorded_at.
recorded_atstringalwaysWhen the device recorded the fix.
received_atstringalwaysWhen the server stored it. Can be earlier than recorded_at if the device clock is wrong.
deviceobjectalwaysinstall_id (always) · session_id (when the SDK set one) · user_id (when the SDK had a user id set at record time).
latitude, longitudenumberalwaysDegrees.
accuracy_mnumberoptionalHorizontal accuracy, metres.
altitude_mnumberoptionalMetres.
speed_mpsnumberoptionalMetres per second.
bearing_degnumberoptionalDegrees.
activitystringoptionalThe device’s raw activity reading: stationary, walking, running, cycling, automotive or unknown. Absent when activity detection is off.
modestringalwaysThe normalised movement mode derived from activity: still, walking, running, cycling, driving or unknown.
qualitystringoptionalThe device’s own opinion of the fix: low_accuracy or implausible_speed. Absent when the device considered it good. Not the server’s verdict — see gate.
battery_percentintegeroptional0–100. 0 is a real reading.
is_charging, power_save_modebooleanoptionalAs reported by the device.
is_mockbooleanalwaysThe OS flagged this fix as a mock location.
triggerstringalwaysWhy the fix was taken: interval, motion, check_in, geofence or manual.
motionstringalwaysmoving, stationary or unknown.
sourcestringalwaysWho produced the location: sdk (the SDK on a device) or server (uploaded with a server key through POST /v1/ingest).
trust_tierstringalwaysunverified, attested or verified. Independent of is_mock.
extrasobjectoptionalYour own string-to-string map, exactly as your app attached it. Treat it as untrusted input.
gateobjectgated locations only{"reason": "low_accuracy" | "implausible_speed" | "mock"}. Absent means admitted.

Optional members are omitted when absent — never null. There is no project_id on a location: the whole page is your project.

Forward compatibility. Ignore members you don’t know, and unknown values of activity, mode, trigger, motion and source. The one exception is gate.reason: if you meet a reason you don’t know, treat the location as gated, never as admitted.

The server checks every uploaded location. A location it judges unusable is gated: it is stored unchanged, with a reason, and kept out of the default view.

You sendYou get
neither include_gated nor gate_reasonadmitted locations only
include_gated=trueadmitted and gated locations together, in one order; gated ones carry gate
gate_reason=mockonly locations gated as mock

This is how you answer “why isn’t my location showing up?” — re-run the window with include_gated=true and look for a gate.

Locations are ordered by the device’s recorded time, not by arrival. Within one walk you get no duplicates and no skips over the locations stored when each page was served.

Devices upload offline-first, so a device that was out of coverage delivers locations dated in the past — possibly into a window you already walked. Those locations will not appear in that finished walk. To reconcile, re-run the window later, or keep a copy with GET /v1/locations/feed, which is ordered by arrival and never skips a late location. (Geofence events work the same way: GET /v1/events is ordered by arrival and guarantees that a walk never skips an event.)

A walk over a window whose to is in the past always ends (next_cursor: null). A to in the future is allowed, but the walk may keep finding new locations.

order=desc reads the same window, with the same filters and limit, newest first: the first page holds the window’s latest locations, and each next_cursor continues toward from. The guarantees above hold in reverse — no duplicates, no skips — and so does the caveat: a location that arrives dated after a position you already passed will not appear in that walk.

Terminal window
curl -s -G https://api.in1.getbeekon.com/v1/locations \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "from=2026-10-01T00:00:00Z" \
--data-urlencode "to=2026-10-07T00:00:00Z" \
--data-urlencode "order=desc" \
--data-urlencode "limit=50"

A cursor belongs to its direction: send it back with the same order (or, for an oldest-first walk, with none — order=asc and no order are the same request). A cursor from one direction sent with the other is 400 cursor_query_mismatch.

Scope: locations:read

The feed serves every location of your project once, in the order the server finished checking it, so you can keep a copy of your locations up to date. A device that was offline delivers locations recorded long ago; in the feed they appear after the cursor you already hold, never before it. Within one upload, locations are ordered by recorded_at, then id.

Terminal window
curl -s -G https://api.in1.getbeekon.com/v1/locations/feed \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "cursor=$CURSOR" \
--data-urlencode "limit=500"
ParameterRequiredMeaning
include_gatednotrue adds gated locations, each with gate, to admitted ones. false (the default) returns admitted locations only. Exactly true or false.
limitno1–500, default 100.
cursornoThe previous page’s next_cursor (prefix lf1_). Absent or empty starts at the oldest position the feed still keeps.

The feed has no window and no filters: from, to, install_id, user_id, gate_reason, mode and order are ignored. The page has the same four members and the same location object as GET /v1/locations, with one difference: next_cursor is never null. Store it and send it on the next call. An empty page means nothing new has arrived yet; poll again later with the same cursor.

What you can rely on.

  • A location is served only once the server has decided whether it is admitted or gated, so its gate never changes after you read it.
  • The feed keeps positions for 7 days. A cursor older than that is 410 expired_cursor: start again without a cursor and fill the gap with GET /v1/locations windows.
  • Locations recorded below retention_floor are never served.
  • Locations stored before the feed existed are not in it. Read them with GET /v1/locations.
  • A location can be served twice after an operator re-admits it, so deduplicate on (id, recorded_at).
  • A cursor belongs to its project. One from another project is 400 cursor_query_mismatch.
StatuserrorWhen
400invalid_include_gatedNot exactly true or false, or repeated.
400invalid_cursorNot a feed cursor this server issued, or repeated.
400cursor_query_mismatchThe cursor was issued for another project.
400limit must be an integer in [1, 500]Bad or repeated limit.
401missing bearer token · invalid session tokenNo valid session.
403server credentials requiredThe token was minted from an SDK key.
403insufficient scopeThe key lacks locations:read.
410expired_cursorThe cursor is older than the feed’s 7 days.
500internal errorA failure on our side. Retry with the same cursor.

Locations older than your plan’s retention are deleted, and retention_floor on each page tells you the boundary.

  • A from below the floor is narrowed, not refused: you get the window from the floor onwards. Compare retention_floor with your from — if your from is earlier, the difference is a permanent gap.
  • A page never contains a location earlier than its own retention_floor.
  • A cursor whose position has fallen below the floor is 410 expired_cursor. Restart with a new from.
StatuserrorWhen
400invalid_windowfrom or to missing, unparseable (a bare date included), repeated, or to not after from.
400window_too_largeinstall_id, user_id, gate_reason or mode present and the window is longer than 24 hours.
400invalid_install_idBlank, over 128 bytes, containing a NUL character, or repeated.
400invalid_user_idEmpty, over 256 bytes, invalid UTF-8, a control character, or repeated.
400invalid_gate_reasonNot one of the three reasons, or repeated.
400invalid_modeNot exactly one of the six modes (case-sensitive), empty, a comma list, or repeated.
400invalid_include_gatedNot exactly true or false, empty, or repeated.
400invalid_orderNot exactly asc or desc (case-sensitive), empty, or repeated.
400conflicting_filtersgate_reason sent together with include_gated.
400invalid_cursorNot a locations cursor this server issued, or repeated.
400cursor_query_mismatchThe cursor was issued for a different window, filters or order.
400limit must be an integer in [1, 500]Bad or repeated limit.
401missing bearer token · invalid session tokenNo valid session.
403the location log is readable by server integrator credentials onlyThe token was minted from an SDK key.
403insufficient scopeThe key lacks locations:read.
410expired_cursorThe cursor’s position is below the retention floor.
500internal errorA failure on our side. Retry with the same cursor.