📖 Afaqy Knowledge Base / AVL / Messages / API Documentation

<aside> CONTENTS

• Introduction
• Monitoring
• Tracking
• Messages
• Second By Second
• Units
• Reports
• Multi-Unit Follow
• Geofences

</aside>

1. Full Integration Flow

This flow describes how to integrate your system with the AVL Message Module from authentication to signal mapping.

1. Authenticate
   • Call the Login endpoint with your credentials.
   • Retrieve the access token from the response.
   • Store the token securely for use in subsequent requests.
2. Retrieve Unit List
   • Use the token to call the Unit List endpoint.
   • Let the user or your system choose the unit to query.
3. Retrieve Signals
   • Call the Signals endpoint for the selected unit.
   • Specify date range, interval, and set sensors to true to receive sensor data.
4. Map Signals to Sensors
   • Interpret returned parameters (prms or root-level keys) and map sensor IDs to names from extra.sensors.
   • Use value or cValue as needed for meaningful readings.
5. Display or Store Data
   • Present mapped sensor data in dashboards or store in your database for analytics.

2. Authentication

Endpoint

POST <https://api.afaqy.sa/auth/login>

Request Body

{
  "data": {
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD"
  }
}

Response

{
  "status": "success",
  "message": "Login successful",
  "data": {
    "token": "YOUR_JWT_TOKEN"
  }
}

3. Unit List

Endpoint

POST <https://api.afaqy.sa/units/lists>

Request Body

{
  "data": {
    "offset": 0,
    "limit": 1000,
    "projection": ["basic", "last_update", "driver"]
  }
}

Response Fields

• _id – Unit unique ID
• name – Unit name
• last_update.dtt – Last update timestamp (ms)
• last_update.lat / last_update.lng – Latest coordinates
• driver.name – Driver assigned to the unit

4. Signals

Endpoint

POST <https://api.afaqy.sa/units/signals>

Request Body Example

{
  "data": {
    "unit_id": "UNIT_ID_HERE",
    "date": {
      "interval": "interval",
      "from": "2025-08-10 00:00:00",
      "to": "2025-08-10 23:59:59",
      "interval_count": 1,
      "interval_unit": "minutes",
      "including_current": false},
    "message_type": "data_messages",
    "message_options": "parameters",
    "parameter": "raw_data",
    "limit": 1000,
    "offset": 0,
    "sensors": true,
    "with_extra": true}
}

5. Mapping & Tracing Returned Data

5.1 Where sensor definitions live

• In each message’s extra.sensors section, you’ll find a mapping of sensor IDs → sensor names.

Example:

"extra": {
  "sensors": {
    "6823325e71b9d5ce20b25d7": "ACC",
    "6823325e71b9d5ce20b25d9": "Vehicle Battery",
    "6823325e71b9d5ce20b25db": "Device Battery"
  }
}

• These IDs are the keys used in the sensors object of the message payload.

5.2 Where sensor readings live

• Inside the sensors object in the main message:

"sensors": {
  "6823325e71b9d5ce20b25d7": {
    "prm": 0,
    "value": "OFF",
    "cValue": "0"
  }
}

Field meanings:

• prm → raw numeric value from the device.
• value → human-readable meaning of the reading.
• cValue → calibrated numeric value after applying sensor calibration rules.

5.3 How to map & interpret

1. Take the sensor ID from sensors.
2. Look it up in extra.sensors to find the sensor’s name.
3. Use value or cValue depending on whether you want calibrated data or raw readings.
4. prm can be used if you need the raw device output for custom processing.

5.4 Mixed parameter sources

• Some parameters (e.g., spd, lat, lng, altitude, ang) appear directly at the root of the message.
• Others (like ACC, fuel, battery) are only in the sensors object and require mapping via extra.sensors.

5.5 Adjustable query parameters that affect mapping

6. Best Practices

• Secure your token; never expose it in client-side code.
• Limit date ranges to reduce payload size and improve performance.
• Use pagination (limit and offset) if you expect large datasets.
• Validate that sensors is enabled in requests when mapping is required.