Setup Monitors

_|

Configure automated event detection for asset tracking including geofence entry/exit, speeding violations, and idle detection.

Overview

Monitors enable automated tracking of asset behaviors by defining rules that trigger events. By assigning properties to monitors, you can track groups of assets sharing common characteristics, enabling efficient collective monitoring.

Monitor Types

Type	Event Trigger	Use Case
enter_and_exit_area	Entry AND exit from geofences	Complete zone tracking
enter_area	Entry only	Arrival notifications
exit_area	Exit only	Departure alerts
speeding	Speed exceeds limit for duration	Speed compliance
idle	No movement for specified time	Idle time tracking

Use Case

A fleet operation needs to:

• Track zone activities for delivery vehicles
• Monitor speed compliance across the fleet
• Detect idle time for operational efficiency
• Alert on violations automatically

Example 1: Area Monitor (Entry/Exit)

Monitor when logistics vans enter or exit delivery zones.

cURL

curl -X POST https://api.magiclane.net/api/v1/add_monitor \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "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", "compliance"],
    "p_properties_filter_type": "all_of",
    "p_properties": {
      "department": "logistics",
      "vehicle_type": "van"
    },
    "p_geofence_config": {
      "geofence_ids": [
        "downtown_delivery_zone",
        "warehouse_safety_perimeter"
      ]
    }
  }'

JavaScript

const setupAreaMonitor = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/add_monitor',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        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', 'compliance'],
        p_properties_filter_type: 'all_of',
        p_properties: {
          department: 'logistics',
          vehicle_type: 'van'
        },
        p_geofence_config: {
          geofence_ids: [
            'downtown_delivery_zone',
            'warehouse_safety_perimeter'
          ]
        }
      })
    }
  );
  
  const result = await response.json();
  console.log(`Monitor created: ${result.id}`);
  return result;
};

await setupAreaMonitor();

Response (code 200 OK)

{
  "id": "delivery_zone_monitor",
  "error": ""
}

Example 2: Area Monitor Using Geofence Keywords

Monitor zones dynamically by keywords instead of specific IDs. This is useful when you want to track all geofences matching certain criteria.

cURL

curl -X POST https://api.magiclane.net/api/v1/add_monitor \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_id": "restricted_zone_monitor",
    "p_type": "enter_and_exit_area",
    "p_name": "Restricted Zone Monitor",
    "p_description": "Track entry/exit for all restricted areas",
    "p_keywords": ["security", "restricted", "compliance"],
    "p_properties_filter_type": "all_of",
    "p_properties": {
      "clearance_level": "high"
    },
    "p_geofence_config": {
      "geofence_keywords": [
        "restricted",
        "security-zone"
      ]
    }
  }'

JavaScript

const setupKeywordMonitor = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/add_monitor',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_id: 'restricted_zone_monitor',
        p_type: 'enter_and_exit_area',
        p_name: 'Restricted Zone Monitor',
        p_description: 'Track entry/exit for all restricted areas',
        p_keywords: ['security', 'restricted', 'compliance'],
        p_properties_filter_type: 'all_of',
        p_properties: {
          clearance_level: 'high'
        },
        p_geofence_config: {
          geofence_keywords: [
            'restricted',
            'security-zone'
          ]
        }
      })
    }
  );
  
  return response.json();
};

await setupKeywordMonitor();

Combining IDs and Keywords

You can use both geofence_ids and geofence_keywords together. All matching geofences are combined with uniqueness ensured:

{
  "p_geofence_config": {
    "geofence_ids": [
      "warehouse_main_entrance",
      "warehouse_loading_dock"
    ],
    "geofence_keywords": [
      "warehouse",
      "restricted"
    ]
  }
}

Benefits of Keyword-Based Configuration:

• Logical grouping: Track all zones of a certain type (e.g., all "parking" areas)
• Scalability: Easily manage monitors across hundreds of geofences

Example 3: Speeding Monitor

Alert when fleet vehicles exceed 72 km/h (20 m/s) for more than 60 seconds.

cURL

curl -X POST https://api.magiclane.net/api/v1/add_monitor \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_id": "fleet_speed_monitor",
    "p_type": "speeding",
    "p_name": "Fleet Speed Compliance Monitor",
    "p_description": "Alert when fleet vehicles exceed 72 km/h (20 m/s) for more than 60 seconds",
    "p_keywords": ["speeding", "compliance", "safety", "fleet"],
    "p_properties_filter_type": "any_of",
    "p_properties": {
      "department": "logistics",
      "vehicle_type": "van"
    },
    "p_speeding_config": {
      "speed_limit": 20,
      "time_tolerance": 60000
    }
  }'

JavaScript

const setupSpeedMonitor = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/add_monitor',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_id: 'fleet_speed_monitor',
        p_type: 'speeding',
        p_name: 'Fleet Speed Compliance Monitor',
        p_description: 'Alert when fleet vehicles exceed 72 km/h (20 m/s) for more than 60 seconds',
        p_keywords: ['speeding', 'compliance', 'safety', 'fleet'],
        p_properties_filter_type: 'any_of',
        p_properties: {
          department: 'logistics',
          vehicle_type: 'van'
        },
        p_speeding_config: {
          speed_limit: 20,        // 20 m/s = 72 km/h
          time_tolerance: 60000   // 60 seconds in milliseconds
        }
      })
    }
  );
  
  return response.json();
};

await setupSpeedMonitor();

Speed Configuration

Parameter	Description	Units
speed_limit	Maximum allowed speed	meters/second
time_tolerance	Duration before triggering	milliseconds

Speed Conversions:

• 20 m/s = 72 km/h = 45 mph
• 25 m/s = 90 km/h = 56 mph
• 30 m/s = 108 km/h = 67 mph

Example 4: Idle Monitor

Detect when freight trucks remain stationary for 10+ minutes.

cURL

curl -X POST https://api.magiclane.net/api/v1/add_monitor \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_id": "truck_idle_monitor",
    "p_type": "idle",
    "p_name": "Freight Truck Idle Monitor",
    "p_description": "Alert when freight trucks are idle for 10+ minutes",
    "p_keywords": ["truck", "idle", "freight", "efficiency"],
    "p_properties_filter_type": "all_of",
    "p_properties": {
      "department": "freight",
      "vehicle_type": "truck"
    },
    "p_idle_config": {
      "time_tolerance": 600000,
      "distance_tolerance": 50
    }
  }'

JavaScript

const setupIdleMonitor = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/add_monitor',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_id: 'truck_idle_monitor',
        p_type: 'idle',
        p_name: 'Freight Truck Idle Monitor',
        p_description: 'Alert when freight trucks are idle for 10+ minutes',
        p_keywords: ['truck', 'idle', 'freight', 'efficiency'],
        p_properties_filter_type: 'all_of',
        p_properties: {
          department: 'freight',
          vehicle_type: 'truck'
        },
        p_idle_config: {
          time_tolerance: 600000,    // 10 minutes
          distance_tolerance: 50      // 50 meters
        }
      })
    }
  );
  
  return response.json();
};

await setupIdleMonitor();

Idle Configuration

Parameter	Description	Units
time_tolerance	Minimum stationary duration	milliseconds
distance_tolerance	Maximum movement allowed	meters

An asset is considered idle if it moves less than distance_tolerance meters during time_tolerance milliseconds.

Property-Based Filtering

Filter Types

all_of - Asset must match ALL specified properties:

{
  p_properties_filter_type: 'all_of',
  p_properties: {
    department: 'logistics',
    vehicle_type: 'van',
    zone: 'downtown'
  }
}

Monitors: Only downtown logistics vans

any_of - Asset must match AT LEAST ONE property:

{
  p_properties_filter_type: 'any_of',
  p_properties: {
    department: 'logistics',
    department_alt: 'freight'
  }
}

Monitors: Assets in either logistics OR freight

Complete Monitoring Setup

Set up comprehensive monitoring for a fleet:

JavaScript

class FleetMonitoringSetup {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.magiclane.net/api/v1';
  }

  async createMonitor(config) {
    const response = await fetch(`${this.baseUrl}/add_monitor`, {
      method: 'POST',
      headers: {
        'Authorization': this.apiKey,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(config)
    });
    return response.json();
  }

  async setupCompleteMonitoring() {
    // 1. Area monitoring for delivery zones
    const areaMonitor = await this.createMonitor({
      p_id: 'delivery_zone_monitor',
      p_type: 'enter_and_exit_area',
      p_name: 'Delivery Zone Monitor',
      p_description: 'Track zone entry/exit for logistics vehicles',
      p_keywords: ['delivery', 'zones'],
      p_properties_filter_type: 'all_of',
      p_properties: {
        department: 'logistics'
      },
      p_geofence_config: {
        geofence_ids: ['downtown_delivery_zone', 'warehouse_perimeter']
      }
    });

    // 2. Speed monitoring for all vehicles
    const speedMonitor = await this.createMonitor({
      p_id: 'fleet_speed_monitor',
      p_type: 'speeding',
      p_name: 'Fleet-Wide Speed Monitor',
      p_description: 'Monitor speed compliance across entire fleet',
      p_keywords: ['speeding', 'compliance'],
      p_properties_filter_type: 'any_of',
      p_properties: {
        department: 'logistics',
        department_alt: 'freight'
      },
      p_speeding_config: {
        speed_limit: 22,       // 80 km/h
        time_tolerance: 45000  // 45 seconds
      }
    });

    // 3. Idle monitoring for trucks
    const idleMonitor = await this.createMonitor({
      p_id: 'truck_idle_monitor',
      p_type: 'idle',
      p_name: 'Truck Idle Efficiency Monitor',
      p_description: 'Reduce idle time for freight trucks',
      p_keywords: ['idle', 'efficiency'],
      p_properties_filter_type: 'all_of',
      p_properties: {
        vehicle_type: 'truck'
      },
      p_idle_config: {
        time_tolerance: 600000,   // 10 minutes
        distance_tolerance: 50
      }
    });

    return {
      area: areaMonitor,
      speed: speedMonitor,
      idle: idleMonitor
    };
  }
}

// Usage
const setup = new FleetMonitoringSetup('YOUR_API_KEY');
const monitors = await setup.setupCompleteMonitoring();

console.log('Monitors created:');
console.log(`- Area: ${monitors.area.id}`);
console.log(`- Speed: ${monitors.speed.id}`);
console.log(`- Idle: ${monitors.idle.id}`);

Event Generation

When monitored conditions occur, events are generated:

Area Event

{
  "asset_id": "vehicle_101",
  "monitor_id": "delivery_zone_monitor",
  "event_type": "enter",
  "geofence_id": "downtown_delivery_zone",
  "event_timestamp": 1754899678,
  "event_location": {
    "lat": 45.641916875,
    "lon": 25.61508875
  },
  "event_metadata": {
    "monitor_type": "enter_and_exit_area"
  },
  "previous_location": {
    "lat": 45.641916875,
    "lon": 25.61508875
  }
}

Speeding Event

{
  "asset_id": "truck_205",
  "monitor_id": "fleet_speed_monitor",
  "event_type": "speeding",
  "event_timestamp": 1754899681,
  "event_location": {
    "lat": 45.6544609375,
    "lon": 25.6024859375
  },
  "event_metadata": {
    "bearing": 25,
    "accuracy": 0.5,
    "speed_mps": 30,
    "speed_limit": 20,
    "total_points": 3,
    "time_window_ms": 60000
  },
  "previous_location": {
    "lat": 45.6544609375,
    "lon": 25.6024859375
  }
}

Idle Event

{
  "asset_id": "truck_205",
  "monitor_id": "truck_idle_monitor",
  "event_type": "idle",
  "event_timestamp": 1754899681,
  "event_location": {
      "lat": 45.6463740625,
      "lon": 25.6214240625
  },
  "event_metadata": {
      "bearing": 25,
      "accuracy": 0.5,
      "speed_mps": 1,
      "total_points": 10,
      "time_window_ms": 600000,
      "speed_threshold": 1.38,
      "total_distance_m": 10,
      "distance_tolerance_m": 50
  },
  "previous_location": {
      "lat": 45.6463740625,
      "lon": 25.6214240625
  }
}

Retrieving Events

Get Event History for a Monitored Asset

cURL

curl -X GET https://api.magiclane.net/api/v1/get_asset_monitor_event_history \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_asset_id": "vehicle_101",
    "p_monitor_id": "delivery_zone_monitor",
    "p_start_time": 1752048576,
    "p_end_time": 1752067081,
    "p_page_no": 1,
    "p_entries_per_page": 20
  }'

JavaScript

const getAssetMonitorEventHistory = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/get_asset_monitor_event_history',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_asset_id: 'vehicle_101',
        p_monitor_id: 'delivery_zone_monitor',
        p_start_time: 1752048576,
        p_end_time: 1752067081,
        p_page_no: 1,
        p_entries_per_page: 20
      })
    }
  );
  
  const data = await response.json();
  const events = data.events_data.list;
  
  console.log(`Found ${data.events_data.page.total_entries} events`);
  
  // Process events
  events.forEach(event => {
    console.log(`${event.event_type.toUpperCase()} - ${event.geofence_id}`);
    console.log(`  Time: ${new Date(event.timestamp * 1000).toLocaleString()}`);
    console.log(`  Location: [${event.triggered_location.location.lat}, ${event.triggered_location.location.lon}]`);
  });
  
  return data;
};

await getAssetMonitorEventHistory();

Example Response:

{
    "events_data": {
        "list": [
            {
                "asset_id": "vehicle_101",
                "meta_data": {
                    "bearing": 45,
                    "accuracy": 0.5,
                    "altitude": null,
                    "speed_mps": 12.5,
                    "monitor_type": "enter_and_exit_area"
                },
                "timestamp": 1752064711,
                "event_type": "enter",
                "monitor_id": "delivery_zone_monitor",
                "geofence_id": "downtown_delivery_zone",
                "prev_location": {
                    "location": {
                        "lat": 45.641500,
                        "lon": 25.614800
                    }
                },
                "monitor_keywords": [
                    "delivery",
                    "zone_monitoring",
                    "compliance"
                ],
                "triggered_location": {
                    "location": {
                        "lat": 45.641916875,
                        "lon": 25.61508875
                    }
                },
                "triggered_timestamp": 1752064711
            },
            {
                "asset_id": "vehicle_101",
                "meta_data": {
                    "bearing": 180,
                    "accuracy": 0.5,
                    "altitude": null,
                    "speed_mps": 8.3,
                    "monitor_type": "enter_and_exit_area"
                },
                "timestamp": 1752054042,
                "event_type": "exit",
                "monitor_id": "delivery_zone_monitor",
                "geofence_id": "downtown_delivery_zone",
                "prev_location": {
                    "location": {
                        "lat": 45.64321,
                        "lon": 25.61792
                    }
                },
                "monitor_keywords": [
                    "delivery",
                    "zone_monitoring",
                    "compliance"
                ],
                "triggered_location": {
                    "location": {
                        "lat": 45.64300,
                        "lon": 25.61780
                    }
                },
                "triggered_timestamp": 1752054042
            },
            ...
        ],
        "page": {
            "page_no": 1,
            "has_more": false,
            "total_pages": 1,
            "total_entries": 4,
            "offset_entries": 0,
            "entries_per_page": 20
        }
    }
}

Poll for New Events for All Assets

cURL

curl -X GET https://api.magiclane.net/api/v1/poll_monitor_events \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_last_poll_timestamp": 1754810032,
    "p_limit": 100,
    "p_sort_order": "asc"
  }'

JavaScript

class EventPoller {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.magiclane.net/api/v1';
    this.lastPollTimestamp = Math.floor(Date.now() / 1000) - 3600; // Start from 1 hour ago
  }

  async pollMonitorEvents() {
    const response = await fetch(
      `${this.baseUrl}/poll_monitor_events`,
      {
        method: 'GET',
        headers: {
          'Authorization': this.apiKey,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        body: JSON.stringify({
          p_last_poll_timestamp: this.lastPollTimestamp,
          p_limit: 100,
          p_sort_order: 'asc'
        })
      }
    );
    
    const data = await response.json();
    const events = data.data.monitor_events;
    
    if (events.length > 0) {
      // Update last poll timestamp to the latest event
      this.lastPollTimestamp = events[events.length - 1].event_timestamp;
      
      console.log(`Received ${events.length} new events`);
      this.processEvents(events);
    } else {
      console.log('No new events');
    }
    
    return events;
  }

  processEvents(events) {
    events.forEach(event => {
      switch(event.event_type) {
        case 'enter':
        case 'exit':
          console.log(`[${event.event_type.toUpperCase()}] ${event.asset_id} - ${event.geofence_id}`);
          break;
        case 'speeding':
          const speedKmh = (event.event_metadata.speed_mps * 3.6).toFixed(1);
          console.log(`[SPEEDING] ${event.asset_id} - ${speedKmh} km/h`);
          break;
        case 'idle':
          const idleMinutes = Math.round(event.event_metadata.time_window_ms / 60000);
          console.log(`[IDLE] ${event.asset_id} - ${idleMinutes} minutes`);
          break;
      }
    });
  }

  // Start continuous polling
  startPolling(intervalSeconds = 10) {
    console.log(`Starting event polling every ${intervalSeconds} seconds...`);
    
    setInterval(async () => {
      try {
        await this.pollMonitorEvents();
      } catch (error) {
        console.error('Error polling events:', error);
      }
    }, intervalSeconds * 1000);
  }
}

// Usage
const poller = new EventPoller('YOUR_API_KEY');
await poller.pollMonitorEvents(); // Poll once

// Or start continuous polling
poller.startPolling(10); // Poll every 10 seconds

Example Response:

{
    "data": {
        "monitor_events": [
            {
                "asset_id": "vehicle_101",
                "event_type": "enter",
                "monitor_id": "delivery_zone_monitor",
                "geofence_id": "downtown_delivery_zone",
                "event_location": {
                    "lat": 45.641916875,
                    "lon": 25.61508875
                },
                "event_metadata": {
                    "bearing": 45,
                    "accuracy": 0.5,
                    "speed_mps": 12.5,
                    "monitor_type": "enter_and_exit_area"
                },
                "event_timestamp": 1767951927,
                "previous_location": {
                    "lat": 45.641500,
                    "lon": 25.614800
                }
            },
            {
                "asset_id": "bike_301",
                "event_type": "idle",
                "monitor_id": "truck_idle_monitor",
                "event_location": {
                    "lat": 59.921903125,
                    "lon": 10.756896875
                },
                "event_metadata": {
                    "bearing": 238,
                    "accuracy": 0.5,
                    "speed_mps": 0,
                    "total_points": 61,
                    "time_window_ms": 600000,
                    "total_distance_m": 12,
                    "speed_threshold_mps": 1.38888888888889,
                    "distance_tolerance_m": 50
                },
                "event_timestamp": 1768315302,
                "previous_location": {
                    "lat": 59.921903125,
                    "lon": 10.756896875
                }
            },
            {
                "asset_id": "truck_205",
                "event_type": "speeding",
                "monitor_id": "fleet_speed_monitor",
                "event_location": {
                    "lat": 59.9221659375,
                    "lon": 10.761776875
                },
                "event_metadata": {
                    "bearing": 189.7,
                    "accuracy": 0.5,
                    "speed_mps": 25.3,
                    "total_points": 9,
                    "time_window_ms": 60000,
                    "speed_threshold_mps": 20
                },
                "event_timestamp": 1768315337,
                "previous_location": {
                    "lat": 59.9224459375,
                    "lon": 10.761871875
                }
            },
            ...
        ]
    }
}

Example Scenarios

Delivery Fleet Management

// Monitor delivery vans in service zones
{
  p_type: 'enter_and_exit_area',
  p_properties: {
    department: 'logistics',
    shift: 'active'
  },
  p_geofence_config: {
    geofence_ids: ['service_zone_1', 'service_zone_2']
  }
}

Safety Compliance

// Monitor all vehicles for speeding
{
  p_type: 'speeding',
  p_properties: {
    company_owned: true
  },
  p_speeding_config: {
    speed_limit: 19.4,    // 70 km/h
    time_tolerance: 60000
  }
}

Operational Efficiency

// Track idle time for cost reduction
{
  p_type: 'idle',
  p_properties: {
    vehicle_type: 'truck',
    fuel_type: 'diesel'
  },
  p_idle_config: {
    time_tolerance: 300000,   // 5 minutes
    distance_tolerance: 30
  }
}

Notes

• Update area monitors when adding new geofences to the system
• Use property filters to group related assets
• Set appropriate time tolerances to avoid false alerts
• Use keywords for organizing monitors
• Don't set time_tolerance too low (< 20 seconds for speed/idle)