Lightbug Documentation

Appearance

GET /devices/{id}/nearbyDevices​

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​

ApiKeyAuth

API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See Authentication for more details.

Type
API Key (header: Authorization)
Example"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Parameters​

Path Parameters

id*

The detecting tracker ID.

Type
number
Required
Format
"integer"

Query Parameters

dateRange

JSON array [start, end] of Unix-millisecond timestamps. Returns the latest reading per nearby device and reading type. Required unless correlationId is supplied.

Type
string
Format
"JSON"
correlationId

Correlation ID from a tracker location point. Takes precedence over dateRange. Required unless dateRange is supplied.

Type
string

Request example

Responses​

Request was successful

application/json
JSON
[
  
{
  
  
"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
  
  
  
}
  
  
}
  
}
]
Try this endpoint

Playground​

Authorization
Variables
Key
Value