Skip to main content
GuidesAPI ReferenceExamples

Add Asset

|

Learn how to register assets for tracking and monitoring in the geofencing system.

Overview​

Assets represent trackable entities such as vehicles, equipment, or personnel. Each asset can have custom properties that enable group-based monitoring and efficient fleet management.

Use Case​

A logistics company needs to:

  • Register delivery vehicles with specific properties
  • Track different vehicle types (vans, trucks, bikes)
  • Group assets by department for collective monitoring
  • Associate assets with users for location updates

Asset Properties​

Properties enable powerful filtering and monitoring capabilities:

{
  "department": "logistics",      // Group by department
  "vehicle_type": "van",          // Filter by type
  "zone": "downtown",             // Geographical assignment
  "capacity_kg": 1000,            // Custom attributes
  "license_plate": "ABC-123"      // Identification
}

Example 1: Add Delivery Van​

Register a delivery van with logistics department properties.

curl -X POST https://api.magiclane.net/api/v1/add_asset \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_id": "vehicle_101",
    "p_name": "Delivery Van 101",
    "p_description": "Primary delivery vehicle for downtown routes",
    "p_properties": {
      "vehicle_type": "van",
      "license_plate": "ABC-123",
      "department": "logistics",
      "zone": "downtown",
      "capacity_kg": 1000
    },
    "p_state": "active",
    "p_type": "user",
    "p_user_id": 1001
  }'

Response (code 200 OK)

{
  "id": "vehicle_101",
  "error": ""
}

Example 2: Add Freight Truck​

Register a heavy-duty truck for long-haul deliveries.

curl -X POST https://api.magiclane.net/api/v1/add_asset \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_id": "truck_205",
    "p_name": "Heavy Duty Truck 205",
    "p_description": "Long-haul freight truck for interstate deliveries",
    "p_properties": {
      "vehicle_type": "truck",
      "license_plate": "XYZ-789",
      "department": "freight",
      "zone": "regional",
      "capacity_kg": 5000,
      "trailer_attached": true
    },
    "p_state": "active",
    "p_type": "user",
    "p_user_id": 2005
  }'

Example 3: Add Courier Bike​

Register an electric bike for express urban deliveries.

curl -X POST https://api.magiclane.net/api/v1/add_asset \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_id": "bike_301",
    "p_name": "Courier Bike 301",
    "p_description": "Electric bike for express urban deliveries",
    "p_properties": {
      "vehicle_type": "e_bike",
      "asset_number": "BK-301",
      "department": "express_delivery",
      "zone": "city_center",
      "battery_range_km": 80
    },
    "p_state": "active",
    "p_type": "user",
    "p_user_id": 3010
  }'

Asset States​

StateDescriptionLocation Updates
activeLocation updated within last 7 daysRecent
inactiveNo updates for 7+ daysStale

Note: Only active assets appear in spatial search results.

Property-Based Monitoring​

Assets with common properties can be monitored collectively:

Example: Monitor All Logistics Vans​

// Asset properties
const van101_properties = {
  department: "logistics",
  vehicle_type: "van"
};

const van102_properties = {
  department: "logistics",
  vehicle_type: "van"
};

// Monitor properties configuration
const monitor_properties = {
  p_properties_filter_type: "all_of",
  p_properties: {
    department: "logistics",
    vehicle_type: "van"
  }
};
// This monitor tracks both van101 and van102

Batch Asset Registration​

Register multiple assets efficiently:

async function registerFleet(assets) {
  const results = [];
  
  for (const asset of assets) {
    const response = await fetch(
      'https://api.magiclane.net/api/v1/add_asset',
      {
        method: 'POST',
        headers: {
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        body: JSON.stringify({
          p_id: asset.id,
          p_name: asset.name,
          p_description: asset.description,
          p_properties: asset.properties,
          p_state: 'active',
          p_type: 'user',
          p_user_id: asset.userId
        })
      }
    );
    
    const result = await response.json();
    results.push({
      id: result.id,
      success: result.error === '',
      error: result.error
    });
  }
  
  return results;
}

// Usage
const fleet = [
  {
    id: 'van_101',
    name: 'Van 101',
    description: 'Downtown delivery',
    properties: { department: 'logistics', vehicle_type: 'van' },
    userId: 1001
  },
  {
    id: 'van_102',
    name: 'Van 102',
    description: 'Suburban delivery',
    properties: { department: 'logistics', vehicle_type: 'van' },
    userId: 1002
  }
];

const results = await registerFleet(fleet);
console.log(`Registered ${results.filter(r => r.success).length} assets`);

Property Naming Examples​

{
  // Identification
  "vehicle_type": "van|truck|bike|car",
  "license_plate": "ABC-123",
  "asset_number": "VAN-001",
  
  // Organization
  "department": "logistics|freight|express",
  "zone": "downtown|regional|city_center",
  
  // Specifications
  "capacity_kg": 1000,
  "fuel_type": "diesel|electric|hybrid",
  
  // Operational
  "shift": "day|night|24_7",
  "driver_assigned": "John Doe",
  
  // Custom
  "battery_range_km": 80,
  "trailer_attached": true
}

Update Asset Information​

Modify asset details after creation:

const updateAsset = async (assetId, updates) => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/update_asset',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_id: assetId,
        p_name: updates.name,
        p_description: updates.description,
        p_properties: updates.properties,
        p_state: updates.state
      })
    }
  );
  
  return response.json();
};

// Update zone assignment
await updateAsset('vehicle_101', {
  properties: {
    zone: 'suburban',
    department: 'logistics'
  }
});

Other Example Use Cases​

Fleet Management​

const assetFleetVehicle = {
  p_id: 'fleet_van_15',
  p_properties: {
    department: 'logistics',
    vehicle_type: 'van',
    zone: 'downtown',
    capacity_kg: 1000,
    fuel_type: 'diesel'
  },
  p_state: 'active',
  p_type: 'user',
  p_user_id: 5015
};

Field Service​

const assetServiceVehicle = {
  p_id: 'service_truck_07',
  p_properties: {
    department: 'field_service',
    vehicle_type: 'service_truck',
    service_area: 'north_region',
    technician: 'Mike Johnson',
    equipment_type: 'HVAC'
  },
  p_state: 'active',
  p_type: 'user',
  p_user_id: 7007
};

Last-Mile Delivery​

const assetCourierBike = {
  p_id: 'courier_bike_23',
  p_properties: {
    department: 'express_delivery',
    vehicle_type: 'e_bike',
    zone: 'city_center',
    battery_range_km: 80,
    shift: 'day'
  },
  p_state: 'active',
  p_type: 'user',
  p_user_id: 2023
};

Notes​

  • Use descriptive asset IDs (e.g., vehicle_101)
  • Include relevant attributes in properties for efficient monitoring
  • Use consistent property naming across assets
  • Don't forget to associate with a valid user_id (configuration needed in the client SDK to enable location updates)
Last updated on