Lightbug Documentation

Appearance

GET /devices/{id}/nearbyDeviceData​

GET
/devices/{id}/nearbyDeviceData

Returns readings for one nearby device detected by the specified tracker during a date range.

Use GET https://api.lightbug.cloud/api/devices/{trackerId}/nearbyDeviceData with your API token in the Authorization header. Both nearbyId (the nearby device's device.id from nearbyDevices) and dateRange are required. Encode dateRange as a JSON array of two Unix-millisecond timestamps.

Replace the placeholders below. The date range is illustrative.

curl --get 'https://api.lightbug.cloud/api/devices/TRACKER_ID/nearbyDeviceData' \
  --header 'Authorization: YOUR_API_TOKEN' \
  --data-urlencode 'nearbyId=NEARBY_DEVICE_ID' \
  --data-urlencode 'dateRange=[1735689600000,1735693200000]'

The response is an object keyed by reading type, with arrays of [timestamp, value] pairs ordered by time. Returned timestamps are rounded Unix seconds, even though the date-range inputs and nearbyDevices reading timestamps use milliseconds. For ble_seen, the returned value is BLE RSSI in dBm. No matching readings returns {}.

Synthetic example (BLE detections only):

{"ble_seen": [[1735689660, -65], [1735689720, -70]]}

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

nearbyId*

The nearby device ID (device.id from nearbyDevices).

Type
string
Required
Format
"JSON"
dateRange*

Required JSON array [start, end] of Unix-millisecond timestamps. Response time-series timestamps use Unix seconds.

Type
string
Required
Format
"JSON"

Request example

Responses​

Request was successful

application/json
JSON
{
}
Try this endpoint

Playground​

Authorization
Variables
Key
Value

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
yaml
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}/nearbyDeviceData:
    get:
      tags:
        - device-misc
      parameters:
        - name: id
          in: path
          description: The detecting tracker ID.
          required: true
          schema:
            type: number
            format: integer
        - name: nearbyId
          in: query
          required: true
          schema:
            type: string
            format: JSON
          description: The nearby device ID (device.id from nearbyDevices).
        - name: dateRange
          in: query
          required: true
          schema:
            type: string
            format: JSON
          description: Required JSON array [start, end] of Unix-millisecond timestamps. Response time-series timestamps use Unix seconds.
      responses:
'200':
yaml
          description: Request was successful
          content:
            application/json:
              schema:
                type: object
yaml
      deprecated: false
      security:
        - ApiKeyAuth: []
      operationId: get-devices-id-nearbyDeviceData
      description: |-
        Returns readings for one nearby device detected by the specified tracker during a date range.

        Use GET `https://api.lightbug.cloud/api/devices/{trackerId}/nearbyDeviceData` with your [API token](/apis/authentication) in the `Authorization` header. Both `nearbyId` (the nearby device's `device.id` from [nearbyDevices](/apis/v1/get-devices-id-nearbyDevices)) and `dateRange` are required. Encode `dateRange` as a JSON array of two Unix-millisecond timestamps.

        Replace the placeholders below. The date range is illustrative.

        ```sh
        curl --get 'https://api.lightbug.cloud/api/devices/TRACKER_ID/nearbyDeviceData' \
          --header 'Authorization: YOUR_API_TOKEN' \
          --data-urlencode 'nearbyId=NEARBY_DEVICE_ID' \
          --data-urlencode 'dateRange=[1735689600000,1735693200000]'
        ```

        The response is an object keyed by reading type, with arrays of `[timestamp, value]` pairs ordered by time. Returned timestamps are rounded Unix **seconds**, even though the date-range inputs and nearbyDevices reading timestamps use **milliseconds**. For `ble_seen`, the returned value is BLE RSSI in dBm. No matching readings returns `{}`.

        Synthetic example (BLE detections only):

        ```json
        {"ble_seen": [[1735689660, -65], [1735689720, -70]]}
        ```
      summary: GET /devices/{id}/nearbyDeviceData
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...