Skip to main content

Device App Locations

The Device App Locations API provides access to location data within your organization's device management system. These endpoints allow you to retrieve detailed information about physical locations where devices are deployed, including address details, geographic coordinates, and organizational metadata. This is essential for asset tracking, geographic reporting, and location-based device management.

Base URL: https://gate.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Device App Locations API is designed to manage and retrieve location information for device deployment tracking. Locations represent physical sites, offices, warehouses, or any other places where your organization's devices are installed or managed.

Key Features:

  • Geographic Data Management: Store complete address information with latitude/longitude coordinates
  • Organizational Hierarchy: Locations are scoped to specific organizations with unique identifiers
  • Flexible Identification: Each location has both a display name and a slug-formatted short name for reports
  • Change Tracking: Built-in timestamps track creation and modification dates
  • Visual Assets: Support for thumbnail images to help identify locations quickly

Common Use Cases:

  • Building device inventory dashboards with geographic visualization
  • Generating location-based reports for asset management
  • Filtering device data by specific sites or regions
  • Creating location hierarchies for multi-site organizations
  • Tracking device deployment history across different facilities

The API follows RESTful principles with paginated responses for efficient data retrieval, making it suitable for both small-scale queries and large enterprise deployments.

Endpoints

GET /device_app_locations/

Description: Retrieves a paginated list of all locations within your organization. This endpoint returns comprehensive location data including address information, geographic coordinates, and organizational metadata. Use this to build location selectors, generate geographic reports, or synchronize location data with external systems.

Use Cases:

  • Populate dropdown menus for device assignment forms
  • Build interactive maps showing all organization locations
  • Export location data for external reporting systems
  • Synchronize with third-party asset management platforms

Full URL Example:

https://gate.zequenze.com/api/v1/device_app_locations/?limit=50&offset=0&last_change__gte=2024-01-01T00:00:00Z

Parameters:

Parameter Type In Required Description
last_change__gte string query No Filter locations modified on or after this date. Format: ISO 8601 datetime (e.g., "2024-01-01T00:00:00Z")
limit integer query No Number of results to return per page. Default is typically 20, maximum varies by configuration
offset integer query No The initial index from which to return results. Use for pagination (e.g., offset=20 for page 2 with limit=20)

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/device_app_locations/?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 125,
  "next": "https://gate.zequenze.com/api/v1/device_app_locations/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Corporate Headquarters",
      "short_name": "hq-main",
      "is_active": true,
      "description": "Main corporate office building with executive offices and IT infrastructure",
      "organization_id": "org_abc123def456",
      "thumbnail": "https://gate.zequenze.com/media/locations/hq_thumb.jpg",
      "address": "1234 Business Ave, Suite 100",
      "reference": "Building A - Main Entrance",
      "city": "San Francisco",
      "postal_code": "94105",
      "state": "California",
      "region": "West Coast",
      "country_code": "US",
      "latitude": "37.7749",
      "longitude": "-122.4194",
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-03-10T14:22:33Z"
    },
    {
      "id": 2,
      "name": "Manufacturing Plant - Phoenix",
      "short_name": "mfg-phoenix",
      "is_active": true,
      "description": "Primary manufacturing facility for hardware production",
      "organization_id": "org_abc123def456",
      "thumbnail": "https://gate.zequenze.com/media/locations/phoenix_plant.jpg",
      "address": "5678 Industrial Blvd",
      "reference": "Plant #1",
      "city": "Phoenix",
      "postal_code": "85001",
      "state": "Arizona",
      "region": "Southwest",
      "country_code": "US",
      "latitude": "33.4484",
      "longitude": "-112.0740",
      "created": "2024-01-20T09:15:00Z",
      "last_change": "2024-02-28T11:45:12Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated location data
401 Unauthorized - Invalid or missing Bearer token
403 Forbidden - Token valid but insufficient permissions
500 Internal Server Error - Contact support if this persists

Common Use Cases

Use Case 1: Building a Location-Based Device Dashboard

Retrieve all active locations to populate a geographic dashboard showing device distribution across your organization's sites. Use the is_active=true filter and combine with device APIs to show real-time asset allocation.

Use Case 2: Synchronizing Location Data for Reports

Use the last_change__gte parameter to fetch only locations modified since your last sync, enabling efficient incremental updates for external reporting systems or data warehouses.

Use Case 3: Creating Location Hierarchies

Leverage the region and organizational structure to build hierarchical location trees for multi-level reporting and device management across geographic regions or business units.

Use Case 4: Mobile App Location Selection

Use the short_name field to create user-friendly location selectors in mobile applications, while maintaining the full address information for detailed views and navigation features.

Use Case 5: Compliance and Asset Tracking

Combine location data with device information to generate compliance reports showing exactly where sensitive equipment is deployed, including full address details and geographic coordinates for audit purposes.

Best Practices

  • Pagination Strategy: Always implement pagination for large location datasets. Start with reasonable page sizes (20-50 items) and adjust based on your application's performance requirements.

  • Incremental Sync: Use the last_change__gte parameter to implement efficient synchronization processes. Store the last sync timestamp and only fetch modified records to minimize API calls and improve performance.

  • Caching Considerations: Location data typically changes infrequently, making it ideal for caching. Cache location lists for 15-30 minutes in most applications, but always respect the last_change timestamp for cache invalidation.

  • Geographic Data Handling: Always validate latitude/longitude values before using them in mapping applications. Some locations may not have precise coordinates, so implement fallback strategies using address geocoding.

  • Error Handling: Implement retry logic for network failures, but avoid aggressive retries on 401/403 responses. Log all API responses for debugging, but never log authentication tokens.

  • Security: Store API tokens securely and rotate them regularly. Never expose tokens in client-side code or public repositories. Use environment variables or secure credential management systems.

Back to top