Get device location report

Tool Name: airdroid_business_get_device_location_report

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Reports & Analytics

Quick Start (Copy & Use)

In one sentence: Query device location records within a specified date range (GPS coordinates, addresses)

What you need: StartDate (start date) + EndDate (end date)

Success criteria: StatusCode == 200 and ErrorMessage is empty; DeviceLocationReport contains location data

What to do next: Analyze device trajectories, generate location reports, geofence monitoring

Minimal request example:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31"
}

Minimal response example:

{
  "DeviceLocationReport": [
    {
      "device_id": "abc123def456ghi789jkl012mno345pq",
      "device_name": "Test Device 01",
      "group_name": "Test Group",
      "note": "Office device",
      "location": {
        "lat": "22.5400",
        "lng": "113.9500"
      },
      "type": "Google Maps",
      "address": "123 Main Street, City",
      "record_time": "2026-01-05 10:30:00"
    }
  ],
  "Pagination": {
    "current_page": 1,
    "last_page": 1,
    "page_size": 50,
    "total": 1
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Query All Device Locations for the Last Week

Scenario: Get an overview of device location trajectories

{
  "StartDate": "2026-01-27",
  "EndDate": "2026-02-03",
  "Timezone": "America/New_York",
  "Page": 1,
  "PageSize": 50
}

Recipe 2: Filter by Device with Extra Fields

Scenario: Query location records for a specific device including device identifier info

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "DeviceIds": ["abc123def456ghi789jkl012mno345pq"],
  "SelectedColumns": ["snid", "model", "imei"],
  "Timezone": "UTC",
  "Page": 1,
  "PageSize": 50
}

Recipe 3: Filter by Group and Keyword

Scenario: Query locations for devices in specific groups matching a keyword

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "GroupIds": [101, 102],
  "Keyword": "Samsung",
  "Timezone": "America/New_York",
  "Page": 1,
  "PageSize": 50
}

Recipe 4: Get Latest Locations by Reverse Time Order

Scenario: Prioritize the most recent location records

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "Ascending": false,
  "Page": 1,
  "PageSize": 50
}

1. Overview

1.1 Description

This tool queries device location record reports within a specified date range, including GPS coordinates, address information, and location type. Suitable for device trajectory analysis, geofence monitoring, location compliance checks, and similar scenarios.

1.2 When to Use

• Trajectory analysis: View device movement trajectories over a time period
• Location verification: Confirm whether devices are in expected areas
• Compliance reports: Generate location-related compliance reports
• Lost device tracking: Find historical location records for lost devices

1.3 Execution Mode & Response

This is a synchronous operation that returns results immediately upon invocation.

• Return value: DeviceLocationReport (location report list) + Pagination (pagination info)
• Timezone support: Timezone can be specified; record_time will display in the specified timezone

1.4 Prerequisites

Important: If location recording frequency is set to "Off", no location data will be recorded and this tool will return an empty list.

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`StartDate`

• Type: string
• Format: YYYY-MM-DD, e.g., 2026-01-15
• Example:

  "2026-01-01"

`EndDate`

• Type: string
• Format: YYYY-MM-DD, e.g., 2026-01-31
• Constraints: Cannot be earlier than StartDate; date range cannot exceed 30 days
• Example:

  "2026-01-31"

`Timezone`

Timezone setting for record_time time conversion.

• Type: string
• Default: UTC
• Common values: UTC, America/New_York, America/Chicago, America/Los_Angeles, Europe/London
• Example:

  "America/New_York"

`DeviceIds`

• Type: string-array
• How to obtain: Via Get All Devices or Get a Device by Name tools
• Combination logic: OR (union) with GroupIds
• Example:

  ["abc123def456ghi789jkl012mno345pq", "def456"]

`GroupIds`

• Type: number-array
• How to obtain: Via Get a Group ID by Group Name tool
• Combination logic: OR (union) with DeviceIds
• Example:

  [1, 2, 3]

`Ascending`

Sort by location record time.

• Type: bool
• Default: true
• Options:
  • true: Ascending (oldest to newest)
  • false: Descending (newest to oldest)
• Tip: Set to false when you need the latest locations
• Example:

  false

`SelectedColumns`

Optional return fields for extra device information.

• Type: string-array
• Default fields (always included): device_id, device_name, group_name, note, location, type, address, record_time
• Optional fields: snid, model, android_id, imsi, imei, mac, eth_mac, manu, tags, group_path
• Example:

  ["snid", "model", "imei"]

2.3 Parameter Combination Logic

• StartDate and EndDate must both be provided
• DeviceIds and GroupIds can be used independently or combined; combined results use OR (union)
• Keyword can be combined with other filter conditions
• SelectedColumns only affects returned fields, not filtering logic

3. Outputs

3.1 Response Examples

Success response:

{
  "DeviceLocationReport": [
    {
      "device_id": "abc123def456ghi789jkl012mno345pq",
      "device_name": "Test Device 01",
      "group_name": "Test Group",
      "note": "Office device",
      "location": {
        "lat": "22.5400",
        "lng": "113.9500"
      },
      "type": "Google Maps",
      "address": "123 Main Street, City",
      "record_time": "2026-01-05 10:30:00"
    }
  ],
  "Pagination": {
    "current_page": 1,
    "last_page": 1,
    "page_size": 50,
    "total": 1
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "DeviceLocationReport": [],
  "Pagination": {},
  "StatusCode": -1,
  "ErrorMessage": "Invalid start_date. Must be a non-empty string."
}

3.2 Field Descriptions

3.3 Pagination Info

Paging strategy:

• When current_page < last_page, use Page + 1 to get the next page
• Consider using DeviceIds, GroupIds, or Keyword to narrow the scope
• Default PageSize=50, maximum supported is 50

4. Examples

4.1 Basic Example: Query All Device Locations for One Month

Request parameters:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "Timezone": "UTC",
  "Page": 1,
  "PageSize": 50
}

4.2 Advanced Example: Get Latest Location for a Specific Device (with Extra Fields)

Request parameters:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "DeviceIds": ["abc123def456ghi789jkl012mno345pq"],
  "SelectedColumns": ["snid", "model", "imei", "manu"],
  "Ascending": false,
  "Page": 1,
  "PageSize": 1
}

4.3 Error Example: Location Recording Not Enabled

Request parameters:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31"
}

Response (empty list):

{
  "DeviceLocationReport": [],
  "Pagination": {
    "current_page": 1,
    "last_page": 1,
    "page_size": 50,
    "total": 0
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

If an empty list is returned, check the "Location Recording Frequency" setting in [Geofencing]-[Settings].

5. Error Handling

5.1 AB Three-Layer Error Codes

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Use SelectedColumns: Only request optional fields you need to reduce response size
• Use filter conditions: Narrow the query scope via DeviceIds, GroupIds, or Keyword
• Maximize PageSize: Use PageSize=50 to reduce request count
• Set reasonable date ranges: Avoid querying excessively long time spans

6.2 Security Notes

🟢 Read operation: This tool only queries location data and has no special security requirements.

Privacy note: Location data is sensitive information; ensure appropriate access control is in place.

6.3 Location Data Prerequisites

Ensure location data is available:

1. Go to [Geofencing] → [Settings] in the AirDroid Business admin console
2. Set "Location Recording Frequency" to a value other than "Off"
3. Devices must have location permissions enabled
4. Devices must have network connectivity to upload location data

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Device Trajectory Analysis Pattern

Scenario: Analyze device movement trajectory over a time period

Tool chain:

Get Device Location Report → Trajectory visualization/analysis

Steps:

1. Set date range and specify DeviceIds
2. Call Get Device Location Report to get location records
3. Sort by record_time
4. Plot trajectory on a map or perform distance calculations

8.2 Geofence Compliance Check Pattern

Scenario: Check whether devices are within allowed areas

Tool chain:

Get Device Location Report → Coordinate comparison → Alert

Steps:

1. Get device location records
2. Compare location.lat and location.lng against geofence boundaries
3. Generate alerts for records outside the boundaries

8.3 Lost Device Tracking Pattern

Scenario: Track historical locations of a lost device

Tool chain:

Get a Device by Name → Get Device Location Report → Enable Lost Mode

Steps:

1. Use Get a Device by Name to get the device ID
2. Call Get Device Location Report to view recent location records
3. After confirming the likely device location, use Enable Lost Mode to lock the device