Skip to main content
GuidesAPI ReferenceExamples

Monitors API

|

Configure automated event detection and alerts for assets.

Overview​

Monitors define rules for tracking asset behavior and generating events. By assigning properties to monitors, you can track groups of assets that share common characteristics, enabling efficient collective monitoring.

Monitor Object Fields​

FieldTypeDescription
idStringUnique identifier for the monitor. Auto-generated UUID if not provided.
typeStringMonitor type: enter_and_exit_area, enter_area, exit_area, speeding, or idle.
nameStringHuman-readable name for the monitor.
descriptionStringDetailed description of the monitor's purpose.
keywordsArrayList of keywords for searching and filtering monitors.
propertiesObjectCustom JSON properties used to identify which assets to monitor.
properties_filter_typeStringHow properties are matched with assets: all_of or any_of.
created_atIntegerUnix timestamp when the monitor was created.
updated_atIntegerUnix timestamp when the monitor was last updated.
configObject• Area monitors: configuration containing geofence IDs to monitor.
• Speeding monitors: configuration for speed threshold monitoring.
• Idle monitors: configuration for idle detection.

Monitor Types​

  • enter_and_exit_area - Triggers notifications on both entry and exit from geofences
  • enter_area - Triggers notifications only when entering geofences
  • exit_area - Triggers notifications only when exiting geofences
  • speeding - Triggers notifications when speed exceeds limit for specified duration
  • idle - Triggers notifications when asset remains stationary beyond tolerance

Add Monitor​

Create a new monitoring rule.

Area Monitor Example​

  • Endpoint: POST /add_monitor

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_id": "delivery_zone_monitor",
  "p_type": "enter_and_exit_area",
  "p_name": "Delivery Zone Entry/Exit Monitor",
  "p_description": "Track when delivery vehicles enter or exit authorized zones",
  "p_keywords": ["delivery", "zone_monitoring"],
  "p_properties_filter_type": "all_of",
  "p_properties": {
    "department": "logistics",
    "vehicle_type": "van"
  },
  "p_geofence_config": {
    "geofence_ids": ["downtown_delivery_zone", "warehouse_safety_perimeter"]
  }
}
  • Response Body: (code 200 OK)
{
    "id": "delivery_zone_monitor",
    "error": ""
}

Speeding Monitor Example​

  • Endpoint: POST /add_monitor

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_id": "fleet_speed_monitor",
  "p_type": "speeding",
  "p_name": "Fleet Speed Compliance Monitor",
  "p_description": "Alert when vehicles exceed 72 km/h for more than 60 seconds",
  "p_properties_filter_type": "any_of",
  "p_properties": {
    "department": "logistics"
  },
  "p_speeding_config": {
    "speed_limit": 20,
    "time_tolerance": 60000
  }
}

Speeding Configuration:

  • speed_limit - Maximum speed in meters/second

  • time_tolerance - Duration in milliseconds before triggering

  • Response Body: (code 200 OK)

{
    "id": "fleet_speed_monitor",
    "error": ""
}

Idle Monitor Example​

  • Endpoint: POST /add_monitor

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_id": "truck_idle_monitor",
  "p_type": "idle",
  "p_name": "Freight Truck Idle Monitor",
  "p_properties": {
    "vehicle_type": "truck"
  },
  "p_idle_config": {
    "time_tolerance": 600000,
    "distance_tolerance": 50
  }
}

Idle Configuration:

  • time_tolerance - Duration in milliseconds

  • distance_tolerance - Maximum movement in meters

  • Response Body: (code 200 OK)

{
    "id": "truck_idle_monitor",
    "error": ""
}

Property Filtering and Monitor Assignments​

Filter Types:

  • all_of - Asset must match all specified properties
  • any_of - Asset must match at least one property

Example Use Cases:

// Monitor only downtown logistics vans
{
  "p_properties_filter_type": "all_of",
  "p_properties": {
    "department": "logistics",
    "vehicle_type": "van",
    "zone": "downtown"
  }
}

// Monitor any freight or logistics vehicles
{
  "p_properties_filter_type": "any_of",
  "p_properties": {
    "department": "freight",
    "department_alt": "logistics"
  }
}

Get Monitors​

Retrieve monitor configurations.

Get by IDs​

  • Endpoint: GET /get_monitors_by_ids

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_ids": ["delivery_zone_monitor", "fleet_speed_monitor"]
}

Get by Keywords​

  • Endpoint: GET /get_monitors_by_keywords

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_keywords": ["delivery"],
  "p_page_no": 1,
  "p_entries_per_page": 20
}
  • Response Body: (code 200 OK)
{
    "monitors": [
        {
            "id": "delivery_zone_monitor",
            "name": "Delivery Zone Entry/Exit Monitor",
            "type": "enter_and_exit_area",
            "keywords": [
                "delivery",
                "zone_monitoring",
                "compliance"
            ],
            "created_at": 1766500544,
            "properties": {
                "department": "logistics",
                "vehicle_type": "van"
            },
            "updated_at": 1766500544,
            "description": "Track when delivery vehicles enter or exit authorized delivery zones",
            "geofence_config": {
                "geofence_ids": [
                    "downtown_delivery_zone",
                    "warehouse_safety_perimeter"
                ]
            },
            "properties_filter_type": "all_of"
        }
    ],
    "page": {
        "total_entries": 1,
        "offset_entries": 0,
        "total_pages": 1,
        "page_no": 1,
        "entries_per_page": 20,
        "has_more": false
    }
}

Get Monitors for Asset​

  • Endpoint: GET /get_monitors_for_asset

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_asset_id": "vehicle_101"
}

Returns all monitors applicable to the asset based on property matching.

  • Response Body: (code 200 OK)
{
  "monitors": [
    {
      "id": "delivery_zone_monitor",
      "type": "enter_and_exit_area",
      "name": "Delivery Zone Entry/Exit Monitor",
      "description": "Track when delivery vehicles enter or exit authorized zones",
      "keywords": ["delivery", "zone_monitoring"],
      "properties_filter_type": "all_of",
      "properties": {
        "department": "logistics",
        "vehicle_type": "van"
      },
      "type_config": {
        "geofence_ids": ["downtown_delivery_zone", "warehouse_safety_perimeter"]
      }
    },
    {
      "id": "fleet_speed_monitor",
      "type": "speeding",
      "name": "Fleet Speed Compliance Monitor",
      "description": "Alert when vehicles exceed 72 km/h for more than 60 seconds",
      "keywords": ["speeding", "compliance"],
      "properties_filter_type": "any_of",
      "properties": {
        "department": "logistics"
      },
      "type_config": {
        "speed_limit": 20,
        "time_tolerance": 60000
      }
    }
  ]
}

Use Cases:

  • Display all active monitors for a specific asset
  • Verify monitoring coverage for fleet vehicles
  • Audit which rules apply to which assets
  • Troubleshoot event detection issues

Monitor Events​

Get Event History​

  • Endpoint: GET /get_asset_monitor_event_history

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_asset_id": "vehicle_101",
  "p_monitor_id": "delivery_zone_monitor",
  "p_start_time": 1752048576,
  "p_end_time": 1752238436,
  "p_page_no": 1,
  "p_entries_per_page": 20
}
  • Response Body: (code 200 OK)
{
  "events": [
    {
      "event_id": "evt_001",
      "asset_id": "vehicle_101",
      "monitor_id": "delivery_zone_monitor",
      "event_type": "enter",
      "triggered_timestamp": 1752050000,
      "triggered_location": {
        "longitude": 25.612887,
        "latitude": 45.647265
      },
      "meta_data": {
        "geofence_id": "downtown_delivery_zone",
        "geofence_name": "Downtown Delivery Zone",
        "monitor_type": "enter_and_exit_area"
      }
    },
    {
      "event_id": "evt_002",
      "asset_id": "vehicle_101",
      "monitor_id": "delivery_zone_monitor",
      "event_type": "exit",
      "triggered_timestamp": 1752053600,
      "triggered_location": {
        "longitude": 25.618423,
        "latitude": 45.651892
      },
      "meta_data": {
        "geofence_id": "downtown_delivery_zone",
        "geofence_name": "Downtown Delivery Zone",
        "monitor_type": "enter_and_exit_area"
      }
    },
    {
      "event_id": "evt_003",
      "asset_id": "vehicle_101",
      "monitor_id": "fleet_speed_monitor",
      "event_type": "speeding",
      "triggered_timestamp": 1752060000,
      "triggered_location": {
        "longitude": 25.625134,
        "latitude": 45.655421
      },
      "meta_data": {
        "speed_mps": 25.5,
        "speed_limit": 20,
        "monitor_type": "speeding"
      }
    }
  ],
  "page": {
    "total_entries": 45,
    "offset_entries": 0,
    "total_pages": 3,
    "page_no": 1,
    "entries_per_page": 20,
    "has_more": true
  }
}

Event Types by Monitor:

  • Area monitors: enter, exit
  • Speeding monitors: speeding
  • Idle monitors: idle

Poll for New Events​

  • Endpoint: GET /poll_monitor_events

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_last_poll_timestamp": 1754810032,
  "p_limit": 10,
  "p_sort_order": "asc"
}
  • Response Body: (code 200 OK)
{
  "events": [
    {
      "event_id": "evt_101",
      "asset_id": "vehicle_101",
      "monitor_id": "delivery_zone_monitor",
      "event_type": "enter",
      "triggered_timestamp": 1754810100,
      "triggered_location": {
        "longitude": 25.612887,
        "latitude": 45.647265
      },
      "meta_data": {
        "geofence_id": "warehouse_safety_perimeter",
        "geofence_name": "Warehouse Safety Perimeter",
        "monitor_type": "enter_and_exit_area"
      }
    },
    {
      "event_id": "evt_102",
      "asset_id": "truck_205",
      "monitor_id": "truck_idle_monitor",
      "event_type": "idle",
      "triggered_timestamp": 1754810500,
      "triggered_location": {
        "longitude": 25.620145,
        "latitude": 45.652338
      },
      "meta_data": {
        "idle_duration_ms": 720000,
        "monitor_type": "idle"
      }
    },
    {
      "event_id": "evt_103",
      "asset_id": "vehicle_101",
      "monitor_id": "fleet_speed_monitor",
      "event_type": "speeding",
      "triggered_timestamp": 1754810800,
      "triggered_location": {
        "longitude": 25.625134,
        "latitude": 45.655421
      },
      "meta_data": {
        "speed_mps": 23.8,
        "speed_limit": 20,
        "monitor_type": "speeding"
      }
    }
  ],
  "latest_timestamp": 1754810800,
  "has_more": false
}

Response Fields:

  • events - Array of events that occurred after p_last_poll_timestamp
  • latest_timestamp - Most recent event timestamp (use for next poll)
  • has_more - Whether more events exist beyond the limit

Polling Best Practices:

  1. Store latest_timestamp from response
  2. Use it as p_last_poll_timestamp in next poll
  3. Poll every 30-60 seconds for real-time monitoring
  4. Use asc sort order to process events chronologically

Sort Options:

  • asc - Oldest events first (default - recommended for polling)
  • desc - Newest events first (for display)

Update Monitor​

Modify existing monitor configuration.

  • Endpoint: POST /update_monitor

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_id": "delivery_zone_monitor",
  "p_properties": {
    "department": "logistics",
    "shift": "day"
  },
  "p_type_config": {
    "geofence_ids": ["downtown_delivery_zone", "suburban_zone"]
  }
}
  • Response Body: (code 200 OK)
{
    "id": "delivery_zone_monitor",
    "error": ""
}

Delete Monitors​

  • Endpoint: DELETE /delete_monitors

  • Headers:

    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
    • Accept: application/json

  • Request Body:

{
  "p_ids": ["old_monitor_1", "test_monitor"]
}
  • Response Body: (code 200 OK)
{
    "deleted_ids": [
        "old_monitor_1", 
        "test_monitor"
    ]
}

Notes​

  • Use properties to group assets for collective monitoring
  • Set appropriate time_tolerance values to avoid false alerts
  • Use keywords for organizing and searching monitors
  • Poll events regularly for real-time alerting systems

API Limits​

  • For polling events the maximum limit is 10,000
  • For requests that support pagination, entries per page can be set to maximum 1000
Last updated on