TWIGZ Backend API Documentation

Overview

The Locations API provides comprehensive location management for the UAE market, including cities and areas with Arabic translations. This system supports delivery zone configuration, store location setup, and customer address management. Location: convex/shared/locations.ts

Get Cities

Retrieves all available cities in the UAE.

const cities = await convex.query(api.shared.locations.getCities);

const cities = await convex.query("shared.locations.getCities");

import requests

response = requests.post(
    f"{CONVEX_URL}/api/query",
    json={
        "path": "shared.locations.getCities",
        "args": {}
    },
    headers={"Authorization": f"Bearer {token}"}
)

cities = response.json()

[
  {
    "_id": "ct123456789",
    "name": "Dubai",
    "nameArabic": "دبي",
    "isActive": true,
    "sortOrder": 1,
    "_creationTime": 1640995200000
  },
  {
    "_id": "ct987654321",
    "name": "Abu Dhabi",
    "nameArabic": "أبو ظبي",
    "isActive": true,
    "sortOrder": 2,
    "_creationTime": 1640995200000
  },
  {
    "_id": "ct555666777",
    "name": "Sharjah",
    "nameArabic": "الشارقة",
    "isActive": true,
    "sortOrder": 3,
    "_creationTime": 1640995200000
  }
]

Get Areas by City

Retrieves all areas within a specific city.

cityId

Id<'cities'>

required

City ID to get areas for

const areas = await convex.query(api.shared.locations.getAreasByCity, { 
  cityId: "ct123456789" 
});

const areas = await convex.query("shared.locations.getAreasByCity", { 
  cityId: "ct123456789" 
});

response = requests.post(
    f"{CONVEX_URL}/api/query",
    json={
        "path": "shared.locations.getAreasByCity",
        "args": {
            "cityId": "ct123456789"
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

areas = response.json()

[
  {
    "_id": "ar123456789",
    "name": "Marina",
    "nameArabic": "مارينا",
    "city": "ct123456789",
    "type": "district",
    "isActive": true,
    "_creationTime": 1640995200000
  },
  {
    "_id": "ar987654321",
    "name": "Downtown Dubai",
    "nameArabic": "وسط مدينة دبي",
    "city": "ct123456789",
    "type": "district",
    "isActive": true,
    "_creationTime": 1640995200000
  },
  {
    "_id": "ar555666777",
    "name": "Jumeirah",
    "nameArabic": "جميرا",
    "city": "ct123456789",
    "type": "neighborhood",
    "isActive": true,
    "_creationTime": 1640995200000
  }
]

Get Location Hierarchy

Retrieves the complete location hierarchy for the entire UAE.

const hierarchy = await convex.query(api.shared.locations.getLocationHierarchy);

const hierarchy = await convex.query("shared.locations.getLocationHierarchy");

{
  "cities": [
    {
      "_id": "ct123456789",
      "name": "Dubai",
      "nameArabic": "دبي",
      "areas": [
        {
          "_id": "ar123456789",
          "name": "Marina",
          "nameArabic": "مارينا",
          "type": "district"
        },
        {
          "_id": "ar987654321",
          "name": "Downtown Dubai",
          "nameArabic": "وسط مدينة دبي",
          "type": "district"
        }
      ]
    },
    {
      "_id": "ct987654321",
      "name": "Abu Dhabi",
      "nameArabic": "أبو ظبي",
      "areas": [
        {
          "_id": "ar111222333",
          "name": "Corniche",
          "nameArabic": "الكورنيش",
          "type": "district"
        }
      ]
    }
  ]
}

Get Location Details

Retrieves detailed location information for a specific city or area.

cityId

Id<'cities'>

City ID for city details

areaId

Id<'areas'>

Area ID for area details

// Get city details
const cityDetails = await convex.query(api.shared.locations.getLocationDetails, {
  cityId: "ct123456789"
});

// Get area details
const areaDetails = await convex.query(api.shared.locations.getLocationDetails, {
  areaId: "ar123456789"
});

// Get city details
const cityDetails = await convex.query("shared.locations.getLocationDetails", {
  cityId: "ct123456789"
});

// Get area details  
const areaDetails = await convex.query("shared.locations.getLocationDetails", {
  areaId: "ar123456789"
});

{
  "type": "city",
  "city": {
    "_id": "ct123456789",
    "name": "Dubai",
    "nameArabic": "دبي",
    "isActive": true,
    "sortOrder": 1,
    "areaCount": 45,
    "storeCount": 125
  }
}

{
  "type": "area",
  "area": {
    "_id": "ar123456789",
    "name": "Marina",
    "nameArabic": "مارينا",
    "city": "ct123456789",
    "cityName": "Dubai",
    "type": "district",
    "isActive": true,
    "storeCount": 15
  }
}

Search Areas

Searches for areas by name (supports both English and Arabic).

searchTerm

string

required

Search term (supports partial matching)

// Search in English
const areas = await convex.query(api.shared.locations.searchAreas, {
  searchTerm: "marina"
});

// Search in Arabic
const areasArabic = await convex.query(api.shared.locations.searchAreas, {
  searchTerm: "مارينا"
});

const areas = await convex.query("shared.locations.searchAreas", {
  searchTerm: "marina"
});

[
  {
    "_id": "ar123456789",
    "name": "Marina",
    "nameArabic": "مارينا",
    "city": "ct123456789",
    "cityName": "Dubai",
    "type": "district",
    "isActive": true
  },
  {
    "_id": "ar444555666",
    "name": "Marina Village",
    "nameArabic": "قرية مارينا",
    "city": "ct987654321",
    "cityName": "Abu Dhabi",
    "type": "community",
    "isActive": true
  }
]

Add Area

Adds a new area to a city (admin function).

cityId

Id<'cities'>

required

City ID to add area to

name

string

required

Area name in English

nameArabic

string

required

Area name in Arabic

type

string

required

Area type: district, neighborhood, community, sector, or zone

const newArea = await convex.mutation(api.shared.locations.addArea, {
  cityId: "ct123456789",
  name: "Business Bay",
  nameArabic: "خليج الأعمال",
  type: "district"
});

const newArea = await convex.mutation("shared.locations.addArea", {
  cityId: "ct123456789",
  name: "Business Bay",
  nameArabic: "خليج الأعمال",
  type: "district"
});

{
  "_id": "ar789012345",
  "name": "Business Bay",
  "nameArabic": "خليج الأعمال",
  "city": "ct123456789",
  "type": "district",
  "isActive": true,
  "_creationTime": 1640995200000
}

Clear Location Data

Clears all location data from the system (admin function - use with caution).

await convex.mutation(api.shared.locations.clearLocationData);

await convex.mutation("shared.locations.clearLocationData");

null

Location Picker Component

Here’s a complete location picker component for your frontend:

import { useState, useEffect } from 'react';
import { useQuery } from 'convex/react';
import { api } from './convex/_generated/api';

interface LocationPickerProps {
  onLocationSelect: (cityId: string, areaId: string) => void;
  selectedCityId?: string;
  selectedAreaId?: string;
}

function LocationPicker({ onLocationSelect, selectedCityId, selectedAreaId }: LocationPickerProps) {
  const [searchTerm, setSearchTerm] = useState('');
  
  const cities = useQuery(api.shared.locations.getCities);
  const areas = useQuery(
    api.shared.locations.getAreasByCity,
    selectedCityId ? { cityId: selectedCityId } : "skip"
  );
  const searchResults = useQuery(
    api.shared.locations.searchAreas,
    searchTerm.length > 2 ? { searchTerm } : "skip"
  );

  const handleCitySelect = (cityId: string) => {
    onLocationSelect(cityId, '');
  };

  const handleAreaSelect = (areaId: string) => {
    if (selectedCityId) {
      onLocationSelect(selectedCityId, areaId);
    }
  };

  return (
    <div className="location-picker">
      {/* Search */}
      <div className="mb-4">
        <input
          type="text"
          placeholder="Search areas..."
          value={searchTerm}
          onChange={(e) => setSearchTerm(e.target.value)}
          className="w-full p-2 border rounded"
        />
        
        {searchResults && searchResults.length > 0 && (
          <div className="mt-2 border rounded max-h-32 overflow-y-auto">
            {searchResults.map((area) => (
              <div
                key={area._id}
                onClick={() => {
                  handleCitySelect(area.city);
                  handleAreaSelect(area._id);
                  setSearchTerm('');
                }}
                className="p-2 hover:bg-gray-100 cursor-pointer"
              >
                <div className="font-medium">{area.name}</div>
                <div className="text-sm text-gray-600">{area.nameArabic} • {area.cityName}</div>
              </div>
            ))}
          </div>
        )}
      </div>

      {/* City Selection */}
      <div className="mb-4">
        <label className="block text-sm font-medium mb-2">City</label>
        <select
          value={selectedCityId || ''}
          onChange={(e) => handleCitySelect(e.target.value)}
          className="w-full p-2 border rounded"
        >
          <option value="">Select a city</option>
          {cities?.map((city) => (
            <option key={city._id} value={city._id}>
              {city.name} - {city.nameArabic}
            </option>
          ))}
        </select>
      </div>

      {/* Area Selection */}
      {selectedCityId && (
        <div className="mb-4">
          <label className="block text-sm font-medium mb-2">Area</label>
          <select
            value={selectedAreaId || ''}
            onChange={(e) => handleAreaSelect(e.target.value)}
            className="w-full p-2 border rounded"
          >
            <option value="">Select an area</option>
            {areas?.map((area) => (
              <option key={area._id} value={area._id}>
                {area.name} - {area.nameArabic} ({area.type})
              </option>
            ))}
          </select>
        </div>
      )}
    </div>
  );
}

export default LocationPicker;

<template>
  <div class="location-picker">
    <!-- Search -->
    <div class="mb-4">
      <input
        v-model="searchTerm"
        type="text"
        placeholder="Search areas..."
        class="w-full p-2 border rounded"
      />
      
      <div v-if="searchResults && searchResults.length > 0" class="search-results">
        <div
          v-for="area in searchResults"
          :key="area._id"
          @click="selectFromSearch(area)"
          class="search-result-item"
        >
          <div class="font-medium">{{ area.name }}</div>
          <div class="text-sm text-gray-600">{{ area.nameArabic }} • {{ area.cityName }}</div>
        </div>
      </div>
    </div>

    <!-- City Selection -->
    <div class="mb-4">
      <label class="block text-sm font-medium mb-2">City</label>
      <select v-model="selectedCityId" @change="onCityChange" class="w-full p-2 border rounded">
        <option value="">Select a city</option>
        <option v-for="city in cities" :key="city._id" :value="city._id">
          {{ city.name }} - {{ city.nameArabic }}
        </option>
      </select>
    </div>

    <!-- Area Selection -->
    <div v-if="selectedCityId" class="mb-4">
      <label class="block text-sm font-medium mb-2">Area</label>
      <select v-model="selectedAreaId" @change="onAreaChange" class="w-full p-2 border rounded">
        <option value="">Select an area</option>
        <option v-for="area in areas" :key="area._id" :value="area._id">
          {{ area.name }} - {{ area.nameArabic }} ({{ area.type }})
        </option>
      </select>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    initialCityId: String,
    initialAreaId: String
  },
  
  emits: ['location-select'],
  
  data() {
    return {
      searchTerm: '',
      selectedCityId: this.initialCityId || '',
      selectedAreaId: this.initialAreaId || '',
      cities: [],
      areas: [],
      searchResults: []
    };
  },
  
  watch: {
    searchTerm: {
      handler: 'searchAreas',
      immediate: false
    },
    selectedCityId: 'loadAreas'
  },
  
  async mounted() {
    await this.loadCities();
    if (this.selectedCityId) {
      await this.loadAreas();
    }
  },
  
  methods: {
    async loadCities() {
      this.cities = await convex.query("shared.locations.getCities");
    },
    
    async loadAreas() {
      if (this.selectedCityId) {
        this.areas = await convex.query("shared.locations.getAreasByCity", {
          cityId: this.selectedCityId
        });
      }
    },
    
    async searchAreas() {
      if (this.searchTerm.length > 2) {
        this.searchResults = await convex.query("shared.locations.searchAreas", {
          searchTerm: this.searchTerm
        });
      } else {
        this.searchResults = [];
      }
    },
    
    selectFromSearch(area) {
      this.selectedCityId = area.city;
      this.selectedAreaId = area._id;
      this.searchTerm = '';
      this.searchResults = [];
      this.loadAreas();
      this.emitSelection();
    },
    
    onCityChange() {
      this.selectedAreaId = '';
      this.emitSelection();
    },
    
    onAreaChange() {
      this.emitSelection();
    },
    
    emitSelection() {
      this.$emit('location-select', {
        cityId: this.selectedCityId,
        areaId: this.selectedAreaId
      });
    }
  }
};
</script>

Area Types

The system supports different area types for better organization:

District

Large administrative divisions within cities (e.g., Downtown Dubai, Marina)

Neighborhood

Residential areas within districts (e.g., Jumeirah 1, Al Barsha)

Community

Planned communities or compounds (e.g., Arabian Ranches, The Springs)

Sector

Industrial or commercial sectors (e.g., DIFC, DMCC)

Error Handling

City not found

Status Code: 404

{
  "error": "City not found",
  "cityId": "ct123456789"
}

Area not found

Status Code: 404

{
  "error": "Area not found",
  "areaId": "ar123456789"
}

Duplicate area name

Status Code: 400

{
  "error": "Area with this name already exists in the city"
}

The location system is specifically designed for the UAE market with comprehensive coverage of major cities and areas, including Arabic translations for better user experience.

Use the search functionality to provide users with a fast way to find their location, especially useful for areas with similar names across different cities.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Locations

Overview

Get Cities

Get Areas by City

Get Location Hierarchy

Get Location Details

Search Areas

Add Area

Clear Location Data

Location Picker Component

Area Types

District

Neighborhood

Community

Sector

Error Handling

​Overview

​Get Cities

​Get Areas by City

​Get Location Hierarchy

​Get Location Details

​Search Areas

​Add Area

​Clear Location Data

​Location Picker Component

​Area Types

District

Neighborhood

Community

Sector

​Error Handling

Overview

Get Cities

Get Areas by City

Get Location Hierarchy

Get Location Details

Search Areas

Add Area

Clear Location Data

Location Picker Component

Area Types

Error Handling