Search Assets in Area

Find active assets within geographical boundaries using circle, envelope (rectangle), or polygon queries.

Overview

Asset spatial search helps you locate vehicles, equipment, or personnel within specific areas. Only assets with location updates in the past 7 days (active state) are returned.

Use Case

A fleet manager needs to:

Find all delivery vans within 1km of a customer location
Identify trucks in a specific warehouse zone
Locate all assets in a city district (polygon)

Example 1: Circle Area Search

Find all logistics vehicles within 1000m of downtown center.

cURL
JavaScript

curl -X GET https://api.magiclane.net/api/v1/search_assets_in_area_circle \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_center_lon": 25.614433,
    "p_center_lat": 45.653820,
    "p_radius_m": 1000,
    "p_properties": {
      "department": "logistics"
    },
    "p_filter": "all_of",
    "p_page_no": 1,
    "p_entries_per_page": 20
  }'

const searchAssetsInCircle = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/search_assets_in_area_circle',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_center_lon: 25.614433,
        p_center_lat: 45.653820,
        p_radius_m: 1000,
        p_properties: {
          department: 'logistics'
        },
        p_filter: 'all_of',
        p_page_no: 1,
        p_entries_per_page: 20
      })
    }
  );
  
  const data = await response.json();
  console.log(`Found ${data.page.total_entries} assets`);
  return data;
};

Example 2: Envelope (Rectangle) Search

Search for all assets in a bounding box area.

cURL
JavaScript

curl -X GET https://api.magiclane.net/api/v1/search_assets_in_area_envelope \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_lonmin": 25.599977,
    "p_latmin": 45.642448,
    "p_lonmax": 25.633650,
    "p_latmax": 45.657558,
    "p_properties": {
      "vehicle_type": "truck"
    },
    "p_filter": "all_of",
    "p_page_no": 1,
    "p_entries_per_page": 20
  }'

const searchAssetsInEnvelope = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/search_assets_in_area_envelope',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_lonmin: 25.599977,
        p_latmin: 45.642448,
        p_lonmax: 25.633650,
        p_latmax: 45.657558,
        p_properties: {
          vehicle_type: 'truck'
        },
        p_filter: 'all_of',
        p_page_no: 1,
        p_entries_per_page: 20
      })
    }
  );
  
  const data = await response.json();
  console.log(`Found ${data.page.total_entries} trucks in area`);
  return data;
};

Example 3: Polygon Area Search

Find assets within an irregular shaped zone (e.g., city district).

cURL
JavaScript

curl -X GET https://api.magiclane.net/api/v1/search_assets_in_area_polygon \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_coordinates": [
      [25.566809, 45.673419],
      [25.560272, 45.658444],
      [25.568433, 45.643670],
      [25.634891, 45.631630],
      [25.662850, 45.654689],
      [25.623632, 45.677563],
      [25.566809, 45.673419]
    ],
    "p_properties": {},
    "p_filter": "any_of",
    "p_page_no": 1,
    "p_entries_per_page": 20
  }'

const searchAssetsInPolygon = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/search_assets_in_area_polygon',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_coordinates: [
          [25.566809, 45.673419],
          [25.560272, 45.658444],
          [25.568433, 45.643670],
          [25.634891, 45.631630],
          [25.662850, 45.654689],
          [25.623632, 45.677563],
          [25.566809, 45.673419]
        ],
        p_properties: {},
        p_filter: 'any_of',
        p_page_no: 1,
        p_entries_per_page: 20
      })
    }
  );
  
  const data = await response.json();
  console.log(`Found ${data.page.total_entries} assets in district`);
  return data;
};

Response Example (code 200 OK)

{
  "assets": [
    {
      "id": "vehicle_101",
      "name": "Delivery Van 101",
      "state": "active",
      "properties": {
        "department": "logistics",
        "vehicle_type": "van",
        "zone": "downtown"
      },
      "last_location": {
        "coordinates": [25.614076, 45.648579],
        "timestamp": 1766482291,
        "speed": 18,
        "bearing": 45
      }
    }
  ],
  "page": {
    "total_entries": 1,
    "page_no": 1,
    "has_more": false
  }
}

Example 4: Get All Active Assets with Last Location

Get a complete list of all active assets and their most recent tracked positions.

cURL
JavaScript

curl -X GET https://api.magiclane.net/api/v1/get_assets_by_properties \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "p_properties": {},
    "p_filter": "all_of",
    "p_page_no": 1,
    "p_entries_per_page": 100
  }'

const getAllActiveAssets = async () => {
  const response = await fetch(
    'https://api.magiclane.net/api/v1/get_assets_by_properties',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        p_properties: {},      // Empty = all assets
        p_filter: 'all_of',
        p_page_no: 1,
        p_entries_per_page: 100
      })
    }
  );
  
  const data = await response.json();
  
  // Extract last known locations
  const assetsWithLocations = data.assets.map(asset => ({
    id: asset.id,
    name: asset.name,
    state: asset.state,
    vehicle_type: asset.properties.vehicle_type,
    department: asset.properties.department,
    last_location: {
      coordinates: asset.last_location.coordinates,
      latitude: asset.last_location.coordinates[1],
      longitude: asset.last_location.coordinates[0],
      speed_kmh: (asset.last_location.speed * 3.6).toFixed(1),
      timestamp: asset.last_location.timestamp,
      last_update: new Date(asset.last_location.timestamp * 1000).toLocaleString()
    }
  }));
  
  console.log(`Found ${assetsWithLocations.length} active assets`);
  
  // Group by department
  const byDepartment = assetsWithLocations.reduce((acc, asset) => {
    const dept = asset.department || 'unassigned';
    if (!acc[dept]) acc[dept] = [];
    acc[dept].push(asset);
    return acc;
  }, {});
  
  console.log('Assets by department:', 
    Object.keys(byDepartment).map(dept => 
      `${dept}: ${byDepartment[dept].length}`
    ).join(', ')
  );
  
  return assetsWithLocations;
};

// Usage
const activeAssets = await getAllActiveAssets();

// Display on map or dashboard
activeAssets.forEach(asset => {
  console.log(`${asset.name}:`);
  console.log(`  Location: [${asset.last_location.latitude}, ${asset.last_location.longitude}]`);
  console.log(`  Speed: ${asset.last_location.speed_kmh} km/h`);
  console.log(`  Last Update: ${asset.last_location.last_update}`);
});

Response Example:

{
  "assets": [
    {
      "id": "vehicle_101",
      "name": "Delivery Van 101",
      "state": "active",
      "properties": {
        "department": "logistics",
        "vehicle_type": "van",
        "zone": "downtown"
      },
      "last_location": {
        "coordinates": [25.614076, 45.648579],
        "speed": 18,
        "bearing": 45,
        "accuracy": 0.5,
        "timestamp": 1766482291
      }
    },
    {
      "id": "truck_205",
      "name": "Heavy Duty Truck 205",
      "state": "active",
      "properties": {
        "department": "freight",
        "vehicle_type": "truck",
        "zone": "regional"
      },
      "last_location": {
        "coordinates": [25.60871, 45.647718],
        "speed": 15,
        "bearing": 25,
        "accuracy": 0.5,
        "timestamp": 1766482291
      }
    }
  ],
  "page": {
    "total_entries": 2,
    "page_no": 1,
    "has_more": false
  }
}

Best Practices

Filtering: Use p_properties to filter by department, zone, or vehicle type for better performance
Caching: Cache results for 30-60 seconds to reduce API calls when displaying on dashboards
State Check: Only assets with state: "active" (location updated in last 7 days) are returned

Note

This endpoint returns only active assets (those with location updates in the past 7 days). Inactive assets are automatically excluded from results.

Property Filtering

Filter Types

all_of - Asset must match ALL specified properties:

{
  "p_properties": {
    "department": "logistics",
    "vehicle_type": "van",
    "zone": "downtown"
  },
  "p_filter": "all_of"
}

Returns: Only assets that are logistics vans in downtown zone

any_of - Asset must match AT LEAST ONE property:

{
  "p_properties": {
    "department": "logistics",
    "department_alt": "freight"
  },
  "p_filter": "any_of"
}

Returns: Assets in either logistics OR freight departments

Pagination

Handle large result sets efficiently:

JavaScript

// Page through all results
let page = 1;
let hasMore = true;
const allAssets = [];

while (hasMore) {
  const response = await searchAssets({ 
    p_page_no: page,
    p_entries_per_page: 100
  });
  
  allAssets.push(...response.assets);
  hasMore = response.page.has_more;
  page++;
}

console.log(`Total assets found: ${allAssets.length}`);

Use Case Examples

Emergency Response

JavaScript

// Find all emergency vehicles near incident
const nearbyVehicles = await searchInCircle({
  center: incidentLocation,
  radius: 5000, // 5km
  properties: { type: 'emergency' }
});

Zone Management

JavaScript

// Check which vehicles are in restricted zone
const unauthorizedVehicles = await searchInPolygon({
  coordinates: restrictedZoneCoords,
  properties: { authorized: false }
});

Resource Allocation

JavaScript

// Find available delivery vans in city
const availableVans = await searchInEnvelope({
  bbox: cityBounds,
  properties: { 
    vehicle_type: 'van',
    status: 'available'
  }
});

Overview​

Use Case​

Example 1: Circle Area Search​

Example 2: Envelope (Rectangle) Search​

Example 3: Polygon Area Search​

Example 4: Get All Active Assets with Last Location​

Property Filtering​

Filter Types​

Pagination​

Use Case Examples​

Emergency Response​

Zone Management​

Resource Allocation​