List Indian City Regions (listCityRegions)

Retrieves stored Indian city region records sorted primarily by position priority (position asc) and secondarily by city name (cityName asc). When a search query is provided, search match results are prioritized strictly by field match hierarchy:

1. cityName (1st Priority)
2. regionName (2nd Priority)
3. countryName (3rd Priority)
4. regionType (4th Priority)
5. fullRegionName (5th Priority)

Supports multi-word AND search, comma-separated OR search, filtering by isPopular, and optional pagination.

HTTP Methods & Route

• GET /api/city-regions/list
• POST /api/city-regions/list

Request Parameters

Query / Body Parameters

Field	Type	Required	Default	Description
search	string	Optional	—	Case-insensitive search keyword filter. Space-separated terms trigger multi-field AND logic; comma-separated terms trigger multi-field OR logic across cityName, regionName, countryName, regionType, and fullRegionName. Results are ordered by field match priority.
countryName	string	Optional	"INDIA"	Case-insensitive country filter.
isPopular	boolean	Optional	—	Filter popular/featured destinations ("true" / "false").
isPaginationNeeded	boolean	Optional	true	Enable or disable pagination ("true" / "false"). When set to false, returns all matching items without pagination wrapper.
page	number	Optional	1	Positive integer representing page number.
limit	number	Optional	50	Positive integer representing items per page.

---

Example Requests

1. GET Request with Search and Pagination

GET /api/city-regions/list?search=MUMBAI&isPopular=true&isPaginationNeeded=true&page=1&limit=20

2. POST Request with Multi-City Search

POST /api/city-regions/list

{
  "search": "MUMBAI, DELHI",
  "countryName": "INDIA",
  "isPopular": true,
  "isPaginationNeeded": true,
  "page": 1,
  "limit": 20
}

---

Response Schemas

1. Paginated Response (isPaginationNeeded: true)

{
  "success": true,
  "data": [
    {
      "id": "c7a8b9f0-1234-5678-90ab-cdef12345678",
      "cityRegionId": 10001,
      "cityName": "MUMBAI",
      "regionName": "MUMBAI",
      "countryName": "INDIA",
      "regionType": "CITY",
      "fullRegionName": "MUMBAI, MAHARASHTRA, INDIA",
      "position": 1,
      "isPopular": true,
      "latitude": 19.076,
      "longitude": 72.8777,
      "isActive": true
    }
  ],
  "message": "Indian city regions retrieved successfully",
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

2. Unpaginated Response (isPaginationNeeded: false)

{
  "success": true,
  "data": [
    {
      "id": "c7a8b9f0-1234-5678-90ab-cdef12345678",
      "cityRegionId": 10001,
      "cityName": "MUMBAI",
      "regionName": "MUMBAI",
      "countryName": "INDIA",
      "regionType": "CITY",
      "fullRegionName": "MUMBAI, MAHARASHTRA, INDIA",
      "position": 1,
      "isPopular": true,
      "latitude": 19.076,
      "longitude": 72.8777,
      "isActive": true,
      "createdAt": "2026-09-09T16:50:00.000Z",
      "updatedAt": "2026-09-09T16:50:00.000Z"
    }
  ],
  "message": "Indian city regions retrieved successfully"
}

3. Validation Error (400 Bad Request)

{
  "success": false,
  "data": {
    "page": {
      "_errors": [
        "Page must be a positive integer"
      ]
    }
  },
  "message": "Validation failed"
}