> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arqq.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Location Management Guide

> Learn how to manage parking locations in your company portfolio using the Arqqin API.

## Overview

Locations represent properties where you manage parking access. Each location can have its own settings, capacity, and vehicle whitelists.

## Adding Locations

Create a new location in your company portfolio:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://apistg.arqq.in/api/locations" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Sunset Towers",
      "slug": "sunset-towers",
      "address": "456 Sunset Boulevard, Dubai Marina",
      "city": "Dubai",
      "country": "UAE",
      "coordinates": {
        "lat": 25.0772,
        "lng": 55.1409
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  async function addLocation(locationData) {
    const response = await fetch('/api/locations', {
      method: 'POST',
      headers: {
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(locationData)
    });

    return response.json();
  }

  const locationData = {
    name: "Sunset Towers",
    slug: "sunset-towers",
    address: "456 Sunset Boulevard, Dubai Marina",
    city: "Dubai",
    country: "UAE",
    coordinates: { lat: 25.0772, lng: 55.1409 }
  };

  const result = await addLocation(locationData);
  ```

  ```python Python theme={null}
  import requests

  def add_location(location_data):
      headers = {
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      }

      response = requests.post(
          '/api/locations',
          headers=headers,
          json=location_data
      )

      return response.json()

  location_data = {
      "name": "Sunset Towers",
      "slug": "sunset-towers",
      "address": "456 Sunset Boulevard, Dubai Marina",
      "city": "Dubai",
      "country": "UAE",
      "coordinates": {"lat": 25.0772, "lng": 55.1409}
  }

  result = add_location(location_data)
  ```
</CodeGroup>

## Listing Locations

### Get All Accessible Locations

Retrieve all locations you have access to:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://apistg.arqq.in/api/locations" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function getAllLocations() {
    const response = await fetch('/api/locations', {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    return response.json();
  }
  ```

  ```python Python theme={null}
  import requests

  def get_all_locations():
      headers = {'X-API-Key': 'YOUR_API_KEY'}
      response = requests.get('/api/locations', headers=headers)
      return response.json()
  ```
</CodeGroup>

### Filter Locations by Company

Filter locations to show only those belonging to a specific company:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://apistg.arqq.in/api/locations?companyId=k17abc123def456ghi789jkl012mno345" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function getLocationsByCompany(companyId) {
    const response = await fetch(`/api/locations?companyId=${companyId}`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    return response.json();
  }

  // Example usage
  const companyId = "k17abc123def456ghi789jkl012mno345";
  const locations = await getLocationsByCompany(companyId);
  ```

  ```python Python theme={null}
  import requests

  def get_locations_by_company(company_id):
      headers = {'X-API-Key': 'YOUR_API_KEY'}
      params = {'companyId': company_id}
      response = requests.get('/api/locations', headers=headers, params=params)
      return response.json()

  # Example usage
  company_id = "k17abc123def456ghi789jkl012mno345"
  locations = get_locations_by_company(company_id)
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "k17xyz789abc123def456ghi012jkl345",
      "name": "Downtown Residences",
      "address": "123 Main Street, Dubai",
      "city": "Dubai",
      "country": "UAE",
      "parkingCapacity": 150,
      "gateCount": 3,
      "isActive": true,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}
```

## Updating Locations

Update an existing location's information using the API key:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://apistg.arqq.in/api/locations/location_123" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Sunset Towers Updated",
      "address": "456 Sunset Boulevard (Renovated), Dubai Marina",
      "city": "Dubai",
      "country": "UAE",
      "coordinates": {
        "lat": 25.0773,
        "lng": 55.1410
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  async function updateLocation(locationId, locationData) {
    const response = await fetch(`/api/locations/${locationId}`, {
      method: 'PUT',
      headers: {
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(locationData)
    });

    return response.json();
  }

  const updateData = {
    name: "Sunset Towers Updated",
    address: "456 Sunset Boulevard (Renovated), Dubai Marina",
    city: "Dubai",
    country: "UAE",
    coordinates: { lat: 25.0773, lng: 55.1410 }
  };

  const result = await updateLocation("location_123", updateData);
  ```

  ```python Python theme={null}
  import requests

  def update_location(location_id, location_data):
      headers = {
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      }

      response = requests.put(
          f'/api/locations/{location_id}',
          headers=headers,
          json=location_data
      )

      return response.json()

  update_data = {
      "name": "Sunset Towers Updated",
      "address": "456 Sunset Boulevard (Renovated), Dubai Marina",
      "city": "Dubai",
      "country": "UAE",
      "coordinates": {"lat": 25.0773, "lng": 55.1410}
  }

  result = update_location("location_123", update_data)
  ```
</CodeGroup>

## Location Status

### Single Location Status

Get status for a specific location:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://apistg.arqq.in/api/locations/location_123/status" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function getLocationStatus(locationId) {
    const response = await fetch(`/api/locations/${locationId}/status`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    return response.json();
  }
  ```
</CodeGroup>

### Bulk Location Status

Get status across all accessible companies, or filter by a specific company using an optional `companyId` query parameter.

<CodeGroup>
  ```bash cURL theme={null}
  # All accessible companies (aggregated)
  curl -X GET "https://apistg.arqq.in/api/locations/status" \
    -H "X-API-Key: YOUR_API_KEY"

  # Specific company
  curl -X GET "https://apistg.arqq.in/api/locations/status?companyId=cmp_123" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // All accessible companies
  async function getAllLocationsStatus() {
    const response = await fetch('/api/locations/status', {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    return response.json();
  }

  // Specific company
  async function getCompanyLocationsStatus(companyId) {
    const response = await fetch(`/api/locations/status?companyId=${encodeURIComponent(companyId)}`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    return response.json();
  }
  ```

  ```python Python theme={null}
  import requests

  def get_all_locations_status():
      return requests.get(
          'https://apistg.arqq.in/api/locations/status',
          headers={ 'X-API-Key': 'YOUR_API_KEY' }
      ).json()

  def get_company_locations_status(company_id: str):
      return requests.get(
          'https://apistg.arqq.in/api/locations/status',
          params={ 'companyId': company_id },
          headers={ 'X-API-Key': 'YOUR_API_KEY' }
      ).json()
  ```
</CodeGroup>

* If `companyId` is provided, your API key must have access to that company; otherwise a 403 is returned.
* If `companyId` is omitted, results are aggregated across all companies your API key can access.

**Aggregated Response (no companyId):**

```json theme={null}
{
  "success": true,
  "data": {
    "companies": [
      { "companyId": "cmp_123", "totalLocations": 3, "lastUpdated": "2025-09-24T12:34:56.000Z" },
      { "companyId": "cmp_456", "totalLocations": 2, "lastUpdated": "2025-09-24T12:34:56.000Z" }
    ],
    "totalLocations": 5,
    "locations": [
      {
        "companyId": "cmp_123",
        "locationId": "loc_abc",
        "locationName": "Downtown Residences",
        "totalCapacity": 150,
        "currentOccupancy": 89,
        "availableSpaces": 61
      }
      
    ],
    "lastUpdated": "2025-09-24T12:34:56.000Z"
  }
}
```

**Filtered Response (with companyId):**

```json theme={null}
{
  "success": true,
  "data": {
    "companies": [
      { "companyId": "cmp_123", "totalLocations": 3, "lastUpdated": "2025-09-24T12:34:56.000Z" }
    ],
    "totalLocations": 3,
    "locations": [
      {
        "companyId": "cmp_123",
        "locationId": "loc_abc",
        "locationName": "Downtown Residences",
        "totalCapacity": 150,
        "currentOccupancy": 89,
        "availableSpaces": 61
      }
      
    ],
    "lastUpdated": "2025-09-24T12:34:56.000Z"
  }
}
```

## Location Fields

<ResponseField name="name" type="string" required>
  Location display name
</ResponseField>

<ResponseField name="slug" type="string" required>
  URL-friendly identifier (lowercase letters, numbers, hyphens only)
</ResponseField>

<ResponseField name="address" type="string" required>
  Physical address
</ResponseField>

<ResponseField name="city" type="string">
  City name
</ResponseField>

<ResponseField name="country" type="string">
  Country name
</ResponseField>

<ResponseField name="coordinates" type="object">
  GPS coordinates with `lat` and `lng` properties
</ResponseField>