List Cities API

Overview

Retrieves the list of cities from the geography master with optional filtering by search term, stateId, or countryId. Supports optional pagination via isPaginationNeeded.

• Endpoint: /api/cities/list
• Method: GET or POST
• Auth Required: No (Public Geography Master)

---

Request Parameters (Query / Body)

Field	Type	Required	Default	Description
search	String	No	undefined	Case-insensitive city name search filter
stateId	Number (Integer)	No	undefined	Filter cities by State ID
countryId	Number (Integer)	No	undefined	Filter cities by Country ID
isPaginationNeeded	Boolean / String	No	false	true (or "true") to return paginated results with metadata; false (or "false") for full list
page	Number (Integer)	No	1	Page number (used when isPaginationNeeded is true)
limit	Number (Integer)	No	10	Page size (used when isPaginationNeeded is true, max 1000)

---

Example 1: Full List without Pagination (isPaginationNeeded = false)

Request

GET /api/cities/list?stateId=21&isPaginationNeeded=false

Response (200 OK)

{
  "success": true,
  "message": "Cities retrieved successfully",
  "data": [
    {
      "id": 254,
      "name": "Mumbai",
      "stateId": 21,
      "countryId": 1,
      "state": {
        "id": 21,
        "name": "Maharashtra",
        "stateCode": "MH"
      },
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      }
    },
    {
      "id": 255,
      "name": "Pune",
      "stateId": 21,
      "countryId": 1,
      "state": {
        "id": 21,
        "name": "Maharashtra",
        "stateCode": "MH"
      },
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      }
    }
  ]
}

---

Example 2: Paginated List (isPaginationNeeded = true)

Request

POST /api/cities/list

{
  "isPaginationNeeded": true,
  "search": "pur",
  "page": 1,
  "limit": 5
}

Response (200 OK)

{
  "success": true,
  "message": "Cities retrieved successfully",
  "data": [
    {
      "id": 89,
      "name": "Ambikapur",
      "stateId": 7,
      "countryId": 1,
      "state": {
        "id": 7,
        "name": "Chhattisgarh",
        "stateCode": "CG"
      },
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      }
    },
    {
      "id": 16,
      "name": "Anantapur",
      "stateId": 2,
      "countryId": 1,
      "state": {
        "id": 2,
        "name": "Andhra Pradesh",
        "stateCode": "AP"
      },
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      }
    }
  ],
  "pagination": {
    "totalItems": 48,
    "currentPage": 1,
    "totalPages": 10,
    "pageSize": 5,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}