Skip to main content

Hostspot Locations

The Hostspot Locations API provides access to physical location data and geographic information for your hotspots. Use this endpoint to retrieve location details, filter by geographic criteria, and manage location metadata for network infrastructure planning and reporting.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Hostspot Locations API enables you to manage and query location data for your network hotspots. This API is essential for organizations that need to track the geographic distribution of their network infrastructure, generate location-based reports, and maintain accurate records of hotspot deployments.

Key capabilities include:

  • Location Management: Retrieve comprehensive location data including addresses, coordinates, and organizational details
  • Geographic Filtering: Filter locations based on coordinate availability for mapping applications
  • Change Tracking: Monitor location updates using timestamp-based filtering for synchronization
  • Pagination Support: Handle large datasets efficiently with built-in pagination controls

The API follows RESTful principles and returns paginated results for optimal performance. Location data includes both basic information (name, description, status) and detailed geographic data (coordinates, addresses, regional information) that can be used for mapping, analytics, and infrastructure planning.

Endpoints

GET /hostspot_locations/

Description: Retrieves a paginated list of hostspot locations with comprehensive filtering options. This endpoint is the primary method for accessing location data and supports various filtering criteria to help you find specific locations or subsets of your location inventory.

Use Cases:

  • Generate reports showing all active hotspot locations across your organization
  • Sync location data with external mapping or analytics systems using timestamp filtering
  • Retrieve only locations with GPS coordinates for mapping applications
  • Build dashboards showing geographic distribution of network infrastructure

Full URL Example:

https://gate.zequenze.com/api/v1/hostspot_locations/?have_coordinates=true&is_active=true&limit=50&offset=0

Parameters:

Parameter Type In Required Description
last_change__gte string query No Filter locations modified on or after this date/time. Accepts ISO format: 2000-01-01, 2000-01-01 00:01:00, or 2000-01-01 00:01:00+00:00
limit integer query No Number of results to return per page (default pagination limit applies)
offset integer query No Starting index for results (used for pagination)
have_coordinates boolean query No When true, returns only locations with both latitude and longitude values set

cURL Example:

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

Example Response:

{
  "count": 247,
  "next": "https://gate.zequenze.com/api/v1/hostspot_locations/?have_coordinates=true&limit=25&offset=25",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Downtown Coffee Shop - Main Street",
      "short_name": "downtown-coffee-main",
      "is_active": true,
      "description": "Primary location serving the downtown business district with high-capacity WiFi access",
      "organization_id": "org_12345",
      "thumbnail": "https://gate.zequenze.com/media/locations/downtown-coffee-thumb.jpg",
      "address": "123 Main Street",
      "reference": "Building A, Ground Floor",
      "city": "San Francisco",
      "postal_code": "94102",
      "state": "California",
      "region": "Pacific",
      "country_code": "US",
      "latitude": "37.7749",
      "longitude": "-122.4194",
      "created": "2024-01-15T09:30:00Z",
      "last_change": "2024-03-10T14:22:15Z"
    },
    {
      "id": 2,
      "name": "University Library - Tech Campus",
      "short_name": "university-library-tech",
      "is_active": true,
      "description": "Educational hotspot providing internet access for students and faculty",
      "organization_id": "org_12345",
      "thumbnail": "https://gate.zequenze.com/media/locations/university-lib-thumb.jpg",
      "address": "456 University Ave",
      "reference": "Library Building, 2nd Floor",
      "city": "Palo Alto",
      "postal_code": "94301",
      "state": "California",
      "region": "Pacific",
      "country_code": "US",
      "latitude": "37.4419",
      "longitude": "-122.1430",
      "created": "2024-01-20T11:15:30Z",
      "last_change": "2024-02-28T16:45:22Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of locations
401 Unauthorized - Invalid or missing Bearer token
400 Bad Request - Invalid parameter values (e.g., malformed date)
429 Too Many Requests - Rate limit exceeded

Common Use Cases

Use Case 1: Building a Location Map

Retrieve all locations with GPS coordinates to display hotspots on an interactive map for network monitoring dashboards.

https://gate.zequenze.com/api/v1/hostspot_locations/?have_coordinates=true&is_active=true

Use Case 2: Synchronizing Location Data

Use timestamp filtering to sync only recently modified locations with external systems, reducing data transfer and processing time.

https://gate.zequenze.com/api/v1/hostspot_locations/?last_change__gte=2024-03-01T00:00:00Z

Use Case 3: Generating Location Reports

Paginate through all locations to create comprehensive reports showing location distribution, status, and organizational assignments.

https://gate.zequenze.com/api/v1/hostspot_locations/?limit=100&offset=0

Use Case 4: Location-Based Analytics

Filter and retrieve location data to analyze geographic patterns, identify coverage gaps, or plan new hotspot deployments.

https://gate.zequenze.com/api/v1/hostspot_locations/?country_code=US&is_active=true

Best Practices

  • Use Pagination Efficiently: Implement proper pagination by following the next and previous URLs in responses rather than manually calculating offsets
  • Filter by Coordinates: When building mapping applications, always use have_coordinates=true to avoid processing locations without geographic data
  • Implement Incremental Sync: Use last_change__gte parameter with stored timestamps to sync only modified locations, improving performance and reducing bandwidth
  • Cache Location Data: Location information typically changes infrequently, making it suitable for caching with appropriate TTL values
  • Handle Rate Limits: Implement exponential backoff when receiving 429 responses, especially when processing large datasets
  • Validate Country Codes: Use the provided country code enum values when filtering or processing location data to ensure consistency
  • Monitor Active Status: Always consider the is_active field when displaying locations to end users or in operational dashboards
Back to top