Lightbug Documentation

Appearance

Get device points​

GET
/devices/{id}/points

Gets one or more points for a device, based on filtering.

Filter limitations

When filtering by time ranges, using the timestamp field, you are limited to at most 90 days of data at a time.
If you request more than 90 days, only the latest 90 days in your range will be returned.
A maximum of 10,000 readings can be returned in one request.

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*

device id

Type
number
Required
Format
"integer"

Query Parameters

filter

Filter criteria for fetching device points.

Type
string
Example{"limit":10,"order":["timestamp DESC"]}{"where":{"timestamp":{"between":["2024-12-01T00:00:00.000Z","2024-12-01T23:59:59.999Z"]}},"order":["timestamp DESC"]}{"where":{"correlationId":"abc123"}}
Format
"JSON"

Request example

Responses​

Request was successful

application/json
JSON
[
  
{
  
  
"location": {
  
  
  
"lat": 0,
  
  
  
"lng": 0
  
  
},
  
  
"timestamp": "string",
  
  
"speed": 0,
  
  
"altitude": 0,
  
  
"course": 0,
  
  
"num_value": "string",
  
  
"stringValue": "string",
  
  
"sendReason": 0,
  
  
"sats": 0,
  
  
"hdop": 0,
  
  
"accuracy": 0,
  
  
"locationType": "gps",
  
  
"batteryVoltage": 0,
  
  
"batteryPct": 0,
  
  
"averageCharge": 0,
  
  
"created": "string",
  
  
"address": "string",
  
  
"alertType": 0,
  
  
"currentUsed": 0,
  
  
"gsmSignal": 0,
  
  
"correlationId": "string",
  
  
"id": 0,
  
  
"deviceId": 0
  
}
]
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}/points:
    get:
      tags:
        - points
      summary: Get device points
      parameters:
        - name: id
          in: path
          description: device id
          required: true
          schema:
            type: number
            format: integer
        - name: filter
          description: Filter criteria for fetching device points.
          in: query
          required: false
          schema:
            type: string
            format: JSON
          example:
            - '{"limit":10,"order":["timestamp DESC"]}'
            - '{"where":{"timestamp":{"between":["2024-12-01T00:00:00.000Z","2024-12-01T23:59:59.999Z"]}},"order":["timestamp DESC"]}'
            - '{"where":{"correlationId":"abc123"}}'
      responses:
'200':
yaml
          description: Request was successful
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    location:
                      properties:
                        lat:
                          type: number
                        lng:
                          type: number
                      type: object
                    timestamp:
                      description: Timestamp for the datapoint. NB this is not necessarily the same as 'created'
                      type: string
                      format: date-time
                    speed:
                      description: Ground velocity in kmh, as determined by the GPS
                      type: number
                      format: ''
                    altitude:
                      description: Altitude in m, as determined by the GPS
                      type: number
                      format: ''
                    course:
                      description: Course in degrees, as determined by the GPS
                      type: number
                      format: ''
                    num_value:
                      description: Internal use only
                      type: string
                    stringValue:
                      description: Internal use only
                      type: string
                    sendReason:
                      description: "Bitfield indicating reason for datapoint transmission and status of the device at the time.\n\r\nBit1(1): Wake mode active, \n\r\nBit2(2): Sleep mode active, \n\r\nBit3(4): Bluetooth disconnected, \n\r\nBit4(8): Outside of Safe-zone, \n\r\nBit5(16): Motion detected, \n\r\nBit6(32): Device started moving, \n\r\nBit7(64): Device stopped moving, \n\r\nBit8(128): Position is stale: last known location was used\n\r\nSpecial case 255/0xFF: device was checking in with server. Ignore all data"
                      type: number
                      format: ''
                    sats:
                      description: Number of visible satellites, as determined by the GPS
                      type: number
                      format: ''
                    hdop:
                      description: Deprecated
                      type: number
                      format: ''
                    accuracy:
                      description: Accuracy of the location in meters
                      type: number
                      format: ''
                    locationType:
                      default: gps
                      description: Type of position. Can be 'gps', 'wifi', 'gsm' or 'invalid'
                      type: string
                    batteryVoltage:
                      description: Battery charge level in volts.
                      type: number
                      format: ''
                    batteryPct:
                      description: Battery charge level in %.
                      type: number
                      format: ''
                    averageCharge:
                      description: Internal Use. 255 indicates plugged in and charging.
                      type: number
                      format: ''
                    created:
                      description: Timestamp for when the datapoint was received and processed by the server
                      type: string
                      format: date-time
                    address:
                      description: A reverse geocode result for the point
                      type: string
                    alertType:
                      description: "Bitfield indicating what alerts where active at transmission time\n\r\nBit1(1): Freefall / Drop detected, \n\r\nBit2(2): Rotation detected, \n\r\nBit3(4): GSM jamming detected, \n\r\nBit4(8): Button was pressed, \n\r\nBit5(16): Generic Alert "
                      type: number
                      format: ''
                    currentUsed:
                      description: Current Used to send this location in microAmp Hours
                      type: number
                      format: ''
                    gsmSignal:
                      description: GSM CSQ value
                      type: number
                      format: ''
                    correlationId:
                      description: Internal use - correlation identifier
                      type: string
                    id:
                      type: number
                      format: ''
                    deviceId:
                      type: number
                      format: ''
                  required:
                    - timestamp
                    - locationType
                    - created
                  type: object
yaml
      deprecated: false
      security:
        - ApiKeyAuth: []
      operationId: get-devices-id-points
      description: |-
        Gets one or more points for a device, based on filtering.

        ### Filter limitations

        When filtering by time ranges, using the `timestamp` field, you are limited to at most 90 days of data at a time.
        If you request more than 90 days, only the latest 90 days in your range will be returned.
        A maximum of 10,000 readings can be returned in one request.
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...