Skip to main content

Device App Locations

Endpoints Summary

Method Path Swagger GET /device_app_locations/ Swagger ↗

The Device App Locations API provides access tocomprehensive location datamanagement functionality for tracking and organizing physical locations within your organization'sorganization. deviceThis managementAPI system. These endpoints allowenables you to retrieve location data with filtering capabilities, manage location hierarchies, and access detailed information about physical locations where devices are deployed, including address details, geographic coordinates, and organizational metadata. This is essentialinformation for asseteach tracking, geographic reporting, and location-based device management.location.

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 andphysical retrievelocations locationwhere informationdevices, equipment, or organizational assets are deployed. This API category serves as the foundation for devicelocation-based deploymenttracking, tracking.reporting, Locationsand representasset physicalmanagement sites,within offices,the warehouses,GATE or any other places where your organization's devices are installed or managed.platform.

Key Features:

  • Retrieve Geographiccomprehensive Datalocation Management:listings Storewith completepagination support
Filter locations by modification date for synchronization workflows Access detailed geographic information including coordinates and address informationdata Manage location hierarchies with latitude/longitudeorganizational coordinatescontext 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 thumbnailboth imagesactive toand helpinactive identifylocation locations quicklytracking

Common UseIntegration Cases:Scenarios:

  • BuildingAsset management systems need to track device inventorylocations dashboardsacross withmultiple geographic visualizationfacilities
  • GeneratingInventory location-basedapplications reportsrequire location data for assetwarehouse and facility management
  • FilteringReporting devicesystems dataneed byto specificgenerate siteslocation-based analytics and summaries
Mobile applications need to display nearby facilities or regionsservice locations CreatingSynchronization processes need to identify recently updated location hierarchies for multi-site organizations Tracking device deployment history across different facilitiesrecords

The API follows RESTfulREST principles with paginatedconsistent JSON responses forand efficientstandard dataHTTP retrieval,status codes, making it suitableeasy forto bothintegrate small-scalewith queriesexisting systems and large enterprise deployments.workflows.

Endpoints

GET /device_app_locations/

Description: Retrieves a paginated list of all locations within your organization. This endpoint returnsprovides comprehensive location data including geographic coordinates, address information, geographicorganizational coordinates,context, and organizational metadata. UseIt thissupports tofiltering buildby locationmodification selectors,date, generatemaking geographicit reports,ideal orfor synchronizesynchronization locationprocesses and incremental data with external systems.updates.

Use Cases:

  • Populate dropdownlocation menusdropdowns forin device assignmentmanagement formsinterfaces
Synchronize location data with external asset management systems Generate location-based reports and analytics dashboards Build interactivefacility mapsfinder showingapplications allwith organizationgeographic locationssearch capabilities ExportMonitor location dataconfiguration forchanges externalover reporting systems Synchronize with third-party asset management platformstime

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.date/time Format: (ISO 8601 datetimeformat). (e.g.,Useful "2024-01-01T00:00:00Z")for incremental synchronization
limit integer query No Number of results to return per page.page Default(default isvaries, typicallyrecommended: 20, maximum varies by configuration10-100)
offset integer query No The initial index from which to return results. Useresults 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=1025&offset=0"last_change__gte=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 125,156,
  "next": "https://gate.zequenze.com/api/v1/device_app_locations/?limit=1025&offset=10"25&last_change__gte=2024-01-15T00:00:00Z",
  "previous": null,
  "results": [
    {
      "id": 1,1001,
      "name": "Downtown Corporate Headquarters",
      "short_name": "hq-main"downtown-hq",
      "is_active": true,
      "description": "Main corporate office building with executive officessuites, IT operations center, and ITprimary infrastructure"data center facilities",
      "organization_id": "org_abc123def456",
      "thumbnail": "https://gate.zequenze.com/media/locations/hq_thumb.thumbnails/downtown-hq.jpg",
      "address": "1234500 BusinessTechnology Ave,Drive, Suite 100",
      "reference": "Building A - Main Entrance"BLDG-001-HQ",
      "city": "San Francisco",
      "postal_code": "94105"94107",
      "state": "California",
      "region": "WestBay Coast"Area",
      "country_code": "US",
      "latitude": "37.7749",
      "longitude": "-122.4194",
      "created": "2024-01-15T10:2023-03-15T09:30:00Z",
      "last_change": "2024-03-10T14:22:01-20T14:45:33Z"
    },
    {
      "id": 2,1002,
      "name": "Manufacturing Plant - Phoenix"North",
      "short_name": "mfg-phoenix"plant-north",
      "is_active": true,
      "description": "Primary manufacturing facility for hardware production"production and quality assurance testing",
      "organization_id": "org_abc123def456",
      "thumbnail": "https://gate.zequenze.com/media/locations/phoenix_plant.thumbnails/plant-north.jpg",
      "address": "56781200 Industrial Blvd"Boulevard",
      "reference": "Plant #1"MFG-PLANT-N01",
      "city": "Phoenix"Portland",
      "postal_code": "85001"97201",
      "state": "Arizona"Oregon",
      "region": "Southwest"Pacific Northwest",
      "country_code": "US",
      "latitude": "33.4484"45.5152",
      "longitude": "-112.0740"122.6784",
      "created": "2024-01-20T09:2023-05-22T11:15:00Z",
      "last_change": "2024-02-28T11:45:12Z"01-18T16:22:15Z"
    },
    {
      "id": 1003,
      "name": "Remote Sales Office - Austin",
      "short_name": "sales-austin",
      "is_active": false,
      "description": "Former regional sales office, relocated operations to Dallas facility",
      "organization_id": "org_abc123def456",
      "thumbnail": null,
      "address": "750 Business Center Drive",
      "reference": "SALES-ATX-03",
      "city": "Austin",
      "postal_code": "78759",
      "state": "Texas",
      "region": "South Central",
      "country_code": "US",
      "latitude": "30.2672",
      "longitude": "-97.7431",
      "created": "2023-01-10T08:00:00Z",
      "last_change": "2024-01-16T10:30:45Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated location data
400
Bad Request - Invalid query parameters (e.g., malformed date) 401 Unauthorized - Invalid or missing BearerAPI token 403 Forbidden - Token valid but insufficientInsufficient permissions to access location data 429 Too Many Requests - Rate limit exceeded 500 Internal Server Error - ContactServer-side supportprocessing if this persistserror

Common Use Cases

Use Case 1: BuildingDevice a Location-Based DeviceAssignment Dashboard

RetrieveBuild allan activeinterface locationswhere administrators can assign devices to specific locations. Use this endpoint to populate alocation geographicdropdown dashboardmenus with active facilities, showing device distribution across your organization's sites. Useboth the is_active=truefull filtername for clarity and combineshort_name withfor devicecompact APIs to show real-time asset allocation.displays.

Use Case 2: Synchronizing LocationIncremental Data for ReportsSynchronization

UseImplement a scheduled sync process that periodically checks for location updates using the last_change__gte parameterparameter. toThis fetch only locations modified since your last sync, enablingenables efficient incremental updates for external reporting systems or data warehouses.synchronization without downloading the entire location dataset each time.

Use Case 3: CreatingGeographic LocationAsset HierarchiesMapping

LeverageCreate interactive maps showing asset distribution across facilities using the regionlatitude/longitude andcoordinates. 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 informationcounts to generatevisualize complianceorganizational presence and asset density.

Use Case 4: Location-Based Reporting

Generate facility utilization reports showingby exactlyfiltering wherelocations sensitivebased equipmenton isactive deployed, including full address detailsstatus and geographicgrouping coordinatesby region or state. Use the reference codes for auditconsistent purposes.identification across different reporting systems.

Use Case 5: Mobile Field Service Applications

Build mobile apps that help technicians find nearby service locations using geographic coordinates. Filter for active locations only and use thumbnail images to help with visual identification of facilities.

Best Practices

    Pagination StrategyManagement::

    Always
    implement pagination for large location datasets. Start withUse reasonable page sizes (20-5025-100 items)records) to balance performance and adjustnetwork based on your application's performance requirements. efficiency Always handle the next and previous URLs for navigation rather than manually calculating offsets Monitor the count field to understand total dataset size for progress indicators

    IncrementalEfficient SyncData Synchronization::

    Use
    theImplement incremental sync using last_change__gte parameter to implement efficient synchronization processes. Storewith the timestamp from your last successful 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 respectStore the last_change timestamp from the most recently updated record for cachethe invalidation.

    next sync cycle Consider implementing exponential backoff for failed sync attempts

    Geographic Data HandlingHandling::

    Always
    validateValidate latitude/longitude valuescoordinates before using them in mapping applications.applications SomeHandle cases where geographic coordinates might be null for some locations Consider implementing geocoding fallbacks using the address fields when coordinates are missing

    Performance Optimization:

      Cache frequently accessed location data locally with appropriate TTL based on your update frequency Use the is_active field to filter out decommissioned locations mayin notuser-facing have precise coordinates, so implement fallback strategies using address geocoding. interfaces Index location data by commonly filtered fields like short_name or reference for faster lookups

      Error HandlingHandling::

        Implement proper retry logic for networktransient failures,errors but(429, avoid500 aggressivestatus retries on 401/403 responses. Log all API responses for debugging, but never log authentication tokens. codes) Validate

        Security:date Store API tokens securely and rotate them regularly. Never expose tokens inparameters client-side codebefore orsending publicrequests repositories.to Useavoid environment400 variableserrors

        orHandle securecases credentialwhere managementlocations systems.might be deleted between API calls (404 responses)
        Back to top