# Locations

> GET /v1/locations — read stored locations for a time window, oldest or newest first, with device, user, movement-mode and admission filters, cursor paging and retention, and GET /v1/locations/feed, every location once in arrival order (locations:read).

Source: https://docs.getbeekon.com/api/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`](#get-v1locationsfeed) instead.

## GET `/v1/locations`

**Scope:** `locations:read`

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

### Parameters

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.

| Parameter       | Required | Meaning                                                                                                                                                                                |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`          | yes      | Inclusive start of the window, on the device’s recorded time.                                                                                                                          |
| `to`            | yes      | **Exclusive** end of the window. Must be after `from`.                                                                                                                                 |
| `install_id`    | no       | Only this device. Max 128 bytes; must not be blank or contain a NUL character.                                                                                                         |
| `user_id`       | no       | Only 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_gated` | no       | `true` to include locations the server gated, alongside admitted ones. `false` (the default) returns admitted locations only. Exactly `true` or `false`, lowercase.                    |
| `gate_reason`   | no       | Only locations gated for this reason: `low_accuracy`, `implausible_speed` or `mock`. Cannot be combined with `include_gated`.                                                          |
| `mode`          | no       | Only locations with this [movement mode](https://docs.getbeekon.com/api/location-mode/): `still`, `walking`, `running`, `cycling`, `driving` or `unknown`. One value; a list is refused.                         |
| `order`         | no       | `asc` (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](#newest-first). |
| `limit`         | no       | 1–500, default 100. See [Pagination](https://docs.getbeekon.com/api/pagination/).                                                                                                                                |
| `cursor`        | no       | The 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.

### The 24-hour cap

`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.

### Response

```json
{
  "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.)

| Member            | Type           | Meaning                                                                                                                                               |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locations`       | array          | The locations, ordered by `recorded_at` ascending (ties broken by `id`), or descending with `order=desc`. `[]` when empty.                            |
| `next_cursor`     | string \| null | The cursor for the next page, or `null` when the window is exhausted.                                                                                 |
| `retention_floor` | string \| null | The earliest instant your project’s data is still kept from, or `null` if nothing has ever been deleted under retention. See [Retention](#retention). |
| `schema_version`  | integer        | `1`.                                                                                                                                                  |

### The location object

| Field                            | Type    | Presence             | Meaning                                                                                                                                                           |
| -------------------------------- | ------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | string  | always               | The location’s id, minted by the device: a lowercase UUID of any version. Unique only together with `recorded_at`.                                                |
| `recorded_at`                    | string  | always               | When the device recorded the fix.                                                                                                                                 |
| `received_at`                    | string  | always               | When the server stored it. Can be earlier than `recorded_at` if the device clock is wrong.                                                                        |
| `device`                         | object  | always               | `install_id` (always) · `session_id` (when the SDK set one) · `user_id` (when the SDK had a user id set at record time).                                          |
| `latitude`, `longitude`          | number  | always               | Degrees.                                                                                                                                                          |
| `accuracy_m`                     | number  | optional             | Horizontal accuracy, metres.                                                                                                                                      |
| `altitude_m`                     | number  | optional             | Metres.                                                                                                                                                           |
| `speed_mps`                      | number  | optional             | Metres per second.                                                                                                                                                |
| `bearing_deg`                    | number  | optional             | Degrees.                                                                                                                                                          |
| `activity`                       | string  | optional             | The device’s raw activity reading: `stationary`, `walking`, `running`, `cycling`, `automotive` or `unknown`. Absent when activity detection is off.               |
| `mode`                           | string  | always               | The normalised [movement mode](https://docs.getbeekon.com/api/location-mode/) derived from `activity`: `still`, `walking`, `running`, `cycling`, `driving` or `unknown`.                    |
| `quality`                        | string  | optional             | The **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_percent`                | integer | optional             | 0–100. `0` is a real reading.                                                                                                                                     |
| `is_charging`, `power_save_mode` | boolean | optional             | As reported by the device.                                                                                                                                        |
| `is_mock`                        | boolean | always               | The OS flagged this fix as a mock location.                                                                                                                       |
| `trigger`                        | string  | always               | Why the fix was taken: `interval`, `motion`, `check_in`, `geofence` or `manual`.                                                                                  |
| `motion`                         | string  | always               | `moving`, `stationary` or `unknown`.                                                                                                                              |
| `source`                         | string  | always               | Who produced the location: `sdk` (the SDK on a device) or `server` (uploaded with a server key through [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/)).                        |
| `trust_tier`                     | string  | always               | `unverified`, `attested` or `verified`. Independent of `is_mock`.                                                                                                 |
| `extras`                         | object  | optional             | Your own string-to-string map, exactly as your app attached it. Treat it as untrusted input.                                                                      |
| `gate`                           | object  | gated 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.

## Admitted and gated locations

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 send                                  | You get                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| neither `include_gated` nor `gate_reason` | admitted locations only                                                      |
| `include_gated=true`                      | admitted and gated locations together, in one order; gated ones carry `gate` |
| `gate_reason=mock`                        | only 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`.

## Ordering and completeness

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`](#get-v1locationsfeed), which is ordered by arrival and never skips a late location. (Geofence events work the same way: [`GET /v1/events`](https://docs.getbeekon.com/api/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.

### Newest first

`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.

```sh
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`.

## GET `/v1/locations/feed`

**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`.

```sh
curl -s -G https://api.in1.getbeekon.com/v1/locations/feed \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  --data-urlencode "cursor=$CURSOR" \
  --data-urlencode "limit=500"
```

| Parameter       | Required | Meaning                                                                                                                                            |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include_gated` | no       | `true` adds gated locations, each with `gate`, to admitted ones. `false` (the default) returns admitted locations only. Exactly `true` or `false`. |
| `limit`         | no       | 1–500, default 100.                                                                                                                                |
| `cursor`        | no       | The 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](#response) and the same [location object](#the-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`.

| Status | `error`                                          | When                                               |
| ------ | ------------------------------------------------ | -------------------------------------------------- |
| 400    | `invalid_include_gated`                          | Not exactly `true` or `false`, or repeated.        |
| 400    | `invalid_cursor`                                 | Not a feed cursor this server issued, or repeated. |
| 400    | `cursor_query_mismatch`                          | The cursor was issued for another project.         |
| 400    | `limit must be an integer in [1, 500]`           | Bad or repeated `limit`.                           |
| 401    | `missing bearer token` · `invalid session token` | No valid session.                                  |
| 403    | `server credentials required`                    | The token was minted from an SDK key.              |
| 403    | `insufficient scope`                             | The key lacks `locations:read`.                    |
| 410    | `expired_cursor`                                 | The cursor is older than the feed’s 7 days.        |
| 500    | `internal error`                                 | A failure on our side. Retry with the same cursor. |

## Retention

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`.

## Errors

| Status | `error`                                                              | When                                                                                             |
| ------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 400    | `invalid_window`                                                     | `from` or `to` missing, unparseable (a bare date included), repeated, or `to` not after `from`.  |
| 400    | `window_too_large`                                                   | `install_id`, `user_id`, `gate_reason` or `mode` present and the window is longer than 24 hours. |
| 400    | `invalid_install_id`                                                 | Blank, over 128 bytes, containing a NUL character, or repeated.                                  |
| 400    | `invalid_user_id`                                                    | Empty, over 256 bytes, invalid UTF-8, a control character, or repeated.                          |
| 400    | `invalid_gate_reason`                                                | Not one of the three reasons, or repeated.                                                       |
| 400    | `invalid_mode`                                                       | Not exactly one of the six modes (case-sensitive), empty, a comma list, or repeated.             |
| 400    | `invalid_include_gated`                                              | Not exactly `true` or `false`, empty, or repeated.                                               |
| 400    | `invalid_order`                                                      | Not exactly `asc` or `desc` (case-sensitive), empty, or repeated.                                |
| 400    | `conflicting_filters`                                                | `gate_reason` sent together with `include_gated`.                                                |
| 400    | `invalid_cursor`                                                     | Not a locations cursor this server issued, or repeated.                                          |
| 400    | `cursor_query_mismatch`                                              | The cursor was issued for a different window, filters or `order`.                                |
| 400    | `limit must be an integer in [1, 500]`                               | Bad or repeated `limit`.                                                                         |
| 401    | `missing bearer token` · `invalid session token`                     | No valid session.                                                                                |
| 403    | `the location log is readable by server integrator credentials only` | The token was minted from an SDK key.                                                            |
| 403    | `insufficient scope`                                                 | The key lacks `locations:read`.                                                                  |
| 410    | `expired_cursor`                                                     | The cursor’s position is below the retention floor.                                              |
| 500    | `internal error`                                                     | A failure on our side. Retry with the same cursor.                                               |
