GET /devices/{id}/nearbyDevices​
Returns nearby devices detected by a tracker, including ZeroN devices and BleTag beacons; results are not restricted to BleTag.
Use GET https://api.lightbug.cloud/api/devices/{trackerId}/nearbyDevices, where trackerId is the detecting tracker's ID (the id path parameter). Send your API token in the Authorization header.
Supply either a correlationId from a location point or dateRange, a JSON array of two Unix-millisecond timestamps. At least one filter is needed: supplying neither returns an empty array. If both are supplied, correlationId takes precedence.
Requests
Replace the placeholders with your token, tracker ID and location point's correlation ID. The date range below is illustrative.
curl --get 'https://api.lightbug.cloud/api/devices/TRACKER_ID/nearbyDevices' \
--header 'Authorization: YOUR_API_TOKEN' \
--data-urlencode 'correlationId=POINT_CORRELATION_ID'
curl --get 'https://api.lightbug.cloud/api/devices/TRACKER_ID/nearbyDevices' \
--header 'Authorization: YOUR_API_TOKEN' \
--data-urlencode 'dateRange=[1735689600000,1735693200000]'
Response
Each array entry contains device metadata (id, name, btMac, ownerId, tags, type, meta) and readings keyed by reading type. Metadata fields can be null or omitted; availability also depends on ownership. Non-BleTag devices are returned only for their owner.
Reading timestamps are Unix milliseconds. For ble_seen, rssi is BLE signal strength in dBm and value mirrors rssi. The example below is entirely synthetic and illustrates only this reading type.
Date-range results contain the latest reading per nearby device and reading type, not every historical observation. Use nearbyDeviceData for a nearby device's time series.
Clients can map detections to their own known fixed beacon locations. This endpoint returns detections; it does not calculate an indoor position.
Authorizations​
API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See Authentication for more details.
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."Parameters​
Path Parameters
The detecting tracker ID.
"integer"Query Parameters
JSON array [start, end] of Unix-millisecond timestamps. Returns the latest reading per nearby device and reading type. Required unless correlationId is supplied.
"JSON"Correlation ID from a tracker location point. Takes precedence over dateRange. Required unless dateRange is supplied.
Request example
Responses​
Request was successful
Try this endpoint
Playground​
Authorization
Variables
OpenAPI definition ​
References are expanded below, except recursive definitions and references with sibling fields. Documentation overrides are included. Full original OpenAPI spec (JSON).
View endpoint OpenAPI definition
openapi: 3.1.0
info:
version: 1.1.0
title: TrackingAPI
description: V1 API for retrieving tracking data and changing settings on Lightbug devices
servers:
- url: https://api.lightbug.cloud/api
externalDocs: {}
security:
- ApiKeyAuth: []
tags: []
paths:
/devices/{id}/nearbyDevices:
get:
tags:
- device-misc
parameters:
- name: id
in: path
description: The detecting tracker ID.
required: true
schema:
type: number
format: integer
- name: dateRange
in: query
required: false
schema:
type: string
format: JSON
description: JSON array [start, end] of Unix-millisecond timestamps. Returns the latest reading per nearby device and reading type. Required unless correlationId is supplied.
- name: correlationId
in: query
required: false
schema:
type: string
description: Correlation ID from a tracker location point. Takes precedence over dateRange. Required unless dateRange is supplied.
responses:'200':
description: Request was successful
content:
application/json:
schema:
type: array
items:
type: object
examples:
synthetic:
summary: Synthetic BLE detections
value:
- device:
id: 1001
name: Example ZeroN
btMac: '02:00:00:00:00:01'
ownerId: 2001
tags: []
type: ZeroN
meta: null
readings:
ble_seen:
timestamp: 1735689660000
value: -65
correlationId: example-point-a
rssi: -65
- device:
id: 1002
name: Example beacon
btMac: '02:00:00:00:00:02'
ownerId: 2001
tags: []
type: BleTag
meta: null
readings:
ble_seen:
timestamp: 1735689660000
value: -72
correlationId: example-point-a
rssi: -72 deprecated: false
security:
- ApiKeyAuth: []
operationId: get-devices-id-nearbyDevices
description: |-
Returns nearby devices detected by a tracker, including ZeroN devices and BleTag beacons; results are not restricted to BleTag.
Use GET `https://api.lightbug.cloud/api/devices/{trackerId}/nearbyDevices`, where `trackerId` is the detecting tracker's ID (the `id` path parameter). Send your [API token](/apis/authentication) in the `Authorization` header.
Supply either a `correlationId` from a [location point](/apis/v1/get-devices-id-points) or `dateRange`, a JSON array of two Unix-millisecond timestamps. At least one filter is needed: supplying neither returns an empty array. If both are supplied, `correlationId` takes precedence.
### Requests
Replace the placeholders with your token, tracker ID and location point's correlation ID. The date range below is illustrative.
```sh
curl --get 'https://api.lightbug.cloud/api/devices/TRACKER_ID/nearbyDevices' \
--header 'Authorization: YOUR_API_TOKEN' \
--data-urlencode 'correlationId=POINT_CORRELATION_ID'
curl --get 'https://api.lightbug.cloud/api/devices/TRACKER_ID/nearbyDevices' \
--header 'Authorization: YOUR_API_TOKEN' \
--data-urlencode 'dateRange=[1735689600000,1735693200000]'
```
### Response
Each array entry contains `device` metadata (`id`, `name`, `btMac`, `ownerId`, `tags`, `type`, `meta`) and `readings` keyed by reading type. Metadata fields can be null or omitted; availability also depends on ownership. Non-BleTag devices are returned only for their owner.
Reading timestamps are Unix milliseconds. For `ble_seen`, `rssi` is BLE signal strength in dBm and `value` mirrors `rssi`. The example below is entirely synthetic and illustrates only this reading type.
Date-range results contain the latest reading per nearby device and reading type, not every historical observation. Use [nearbyDeviceData](/apis/v1/get-devices-id-nearbyDeviceData) for a nearby device's time series.
Clients can map detections to their own known fixed beacon locations. This endpoint returns detections; it does not calculate an indoor position.
summary: GET /devices/{id}/nearbyDevices
components:
securitySchemes:
ApiKeyAuth:
in: header
name: Authorization
type: apiKey
description: API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See <a href='/apis/authentication'>Authentication</a> for more details.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...