Overview

SERVICE DESCRIPTION

This service provides integration with the LYTX video telematics platform through the GHUBEE interface. It enables retrieval of driver performance and safety events with comprehensive metadata including event triggers, coaching status, and vehicle information. The service automatically enriches raw event data by combining multiple LYTX API endpoints to provide complete context for each safety event.

INTEGRATION SPECIFICATION
Service Details

Service Name	LYTX Driver Performance Events
Context	/lytx/driver-performance-events/
Description	Retrieves driver performance and safety events from LYTX video telematics system with enriched metadata. Automatically combines data from triggers, statuses, and vehicles endpoints to provide comprehensive event information.
Endpoint	https://hml.ghubee.com/api/lytx/driver-performance-events/
Environment Specifications	https://ghubee.com/api
Protocol/Transport	HTTPS
Method	GET
Representation format	JSON
Input/Output Interface or Both	Both
Data transformation	Yes - Enriches events with trigger names, coaching statuses, and vehicle information

Assumption

The service must be invoked with all mandatory parameters correctly filled.

Authentication is required to access LYTX services through GHUBEE using Bearer token.

LYTX API key must be provided in the request header (api-key-eld) for authentication with LYTX API.

Date parameters are automatically formatted to ISO 8601 format with time boundaries (start: T00:00:00.00Z, end: T23:59:59.99Z).

ENDPOINT 1: Get Driver Performance Events

URL: GET https://hml.ghubee.com/api/lytx/driver-performance-events/

Data input

Field	Description	Format	Required	Remarks
Token_Ghubee	GHUBEE authentication token	Authorization Header	Yes	Bearer token
api-key-eld	LYTX API key	Custom Header	Yes	x-apikey for LYTX authentication
driver_ids	Driver ID filter	Query Parameter	No	Comma-separated driver IDs
vehicle_ids	Vehicle ID filter	Query Parameter	No	Comma-separated vehicle IDs
start_date	Start date for filtering	Query Parameter	No	YYYY-MM-DD (converted to T00:00:00.00Z)
end_date	End date for filtering	Query Parameter	No	YYYY-MM-DD (converted to T23:59:59.99Z)
page	Page number for pagination	Query Parameter	No	Integer value for page offset
dateOption	Date field to filter by	Query Parameter	No	Default: lastUpdatedDate
sortDirection	Sort order	Query Parameter	No	asc or desc (Default: desc)
sortBy	Field to sort results by	Query Parameter	No	Default: lastUpdatedDate
includeSubgroups	Include subgroups flag	Query Parameter	No	true or false (Default: true)
limit	Maximum results per request	Query Parameter	No	Integer (Default: 1000)

Example:

GET https://hml.ghubee.com/api/lytx/driver-performance-events/?start_date=2025-01-01&end_date=2025-01-07&limit=100&sortDirection=desc
Authorization: Bearer token_ghubee_here
api-key-eld: your_lytx_api_key_here

Data output

Field	Description	Format	Required	Remarks
status	Response status	String	Yes	Success / Error
message	Response message	String	Yes	Status description
data	Array of safety events	Array	Yes	Driver performance events
data[].id	Event unique identifier	Integer	Yes	LYTX event ID
data[].eventTriggerId	Trigger type ID	Integer	Yes	References trigger catalog
data[].type	Event trigger name	String	Yes	Enriched: Hard Braking, Speeding, etc.
data[].eventStatusId	Coaching status ID	Integer	Yes	References status catalog
data[].coaching_status	Coaching status name	String	Yes	Enriched: Coached, Pending, Dismissed
data[].vehicleId	Vehicle identifier	String	Yes	LYTX dcVehicleId
data[].vehicle	Complete vehicle object	Object	Yes	Enriched vehicle information
vehicle.dcVehicleId	Vehicle ID	String	Yes	Vehicle identifier
vehicle.name	Vehicle name	String	Yes	Display name (e.g., Truck 101)
vehicle.vin	Vehicle VIN	String	No	Vehicle Identification Number
vehicle.licensePlate	License plate	String	No	Vehicle license plate number
vehicle.make	Vehicle make	String	No	Manufacturer (e.g., Freightliner)
vehicle.model	Vehicle model	String	No	Model name (e.g., Cascadia)
vehicle.year	Vehicle year	Integer	No	Manufacture year
data[].driverId	Driver identifier	String	Yes	Driver associated with event
data[].eventDate	Event occurrence date/time	String	Yes	ISO 8601 format (e.g., 2025-01-05T14:32:15.000Z)
data[].lastUpdatedDate	Last update date/time	String	Yes	ISO 8601 format
data[].severity	Event severity level	String	No	High, Medium, Low
data[].duration	Event duration	Number	No	Duration in seconds
data[].speed	Vehicle speed during event	Number	No	Speed value (mph/kph)
data[].latitude	GPS latitude	Number	No	Decimal degrees
data[].longitude	GPS longitude	Number	No	Decimal degrees
data[].videoUrl	Video playback URL	String	No	Link to event video (if available)

Example Response (Success - 200):

{
  "status": "Success",
  "message": "Success",
  "data": [
    {
      "id": 123456789,
      "eventTriggerId": 5,
      "type": "Hard Braking",
      "eventStatusId": 2,
      "coaching_status": "Coached",
      "vehicleId": "V123456",
      "vehicle": {
        "dcVehicleId": "V123456",
        "name": "Truck 101",
        "vin": "1HGBH41JXMN109186",
        "licensePlate": "ABC1234",
        "make": "Freightliner",
        "model": "Cascadia",
        "year": 2023
      },
      "driverId": "D789012",
      "eventDate": "2025-01-05T14:32:15.000Z",
      "lastUpdatedDate": "2025-01-06T09:15:30.000Z",
      "severity": "High",
      "duration": 3.5,
      "speed": 65.2,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "videoUrl": "https://lytx-api.prod5.ph.lytx.com/video/play/123456789"
    }
  ]
}

Error messages

Identification and description of error message types.

Situation	Message Code	Message description
Unauthenticated	{ "status": "Error", "message": "Unauthenticated", "data": null }	Authentication error with GHUBEE. Bearer token missing or invalid.
Missing API Key	{ "status": "Error", "message": "API key is missing or invalid.", "data": null }	LYTX API key (api-key-eld header) is missing or invalid.
cURL Error	{ "status": "Error", "message": "cURL error: [error details]", "data": null }	Communication error with LYTX API. Could be connection timeout or network issue.
Invalid JSON Response	{ "status": "Error", "message": "Invalid JSON response", "data": null }	LYTX API returned invalid JSON data.
LYTX API Error	{ "status": "Error", "message": "[LYTX error message]", "data": null }	Error returned by LYTX API (e.g., invalid parameters, authorization failed).