List States API

Overview

Retrieves the list of states and union territories from the geography master with optional filtering by search term or countryId. Supports optional pagination via isPaginationNeeded.

• Endpoint: /api/states/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 search filter matching state name or state code
countryId	Number (Integer)	No	undefined	Filter states 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/states/list?countryId=1&isPaginationNeeded=false

Response (200 OK)

{
  "success": true,
  "message": "States retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Andaman and Nicobar Islands",
      "stateCode": "AN",
      "countryId": 1,
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      },
      "_count": {
        "cities": 6
      }
    },
    {
      "id": 2,
      "name": "Andhra Pradesh",
      "stateCode": "AP",
      "countryId": 1,
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      },
      "_count": {
        "cities": 24
      }
    }
  ]
}

---

Example 2: Paginated List (isPaginationNeeded = true)

Request

POST /api/states/list

{
  "isPaginationNeeded": true,
  "search": "maharashtra",
  "page": 1,
  "limit": 10
}

Response (200 OK)

{
  "success": true,
  "message": "States retrieved successfully",
  "data": [
    {
      "id": 21,
      "name": "Maharashtra",
      "stateCode": "MH",
      "countryId": 1,
      "country": {
        "id": 1,
        "name": "India",
        "iso2": "IN",
        "iso3": "IND"
      },
      "_count": {
        "cities": 42
      }
    }
  ],
  "pagination": {
    "totalItems": 1,
    "currentPage": 1,
    "totalPages": 1,
    "pageSize": 10,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}