# Get Ward (New)

> List the wards/communes of a province under the 2-level administrative model.

> **NOTE**
> **New 2-level address model.** Wards belong directly to a province — there is no district tier. The returned `name` is exactly what you pass as `to_ward_name` in [Create Order](https://developer.ghn.vn/en/docs/order/create.md) with `is_new_to_address: true`. The legacy district-based catalogue remains at [Get Ward](https://developer.ghn.vn/en/docs/master-data/get-ward.md).

## Endpoint

| Environment | URL |
| --- | --- |
| Production | `https://online-gateway.ghn.vn/shiip/public-api/v3/master-data/ward/all-by-province-id` |
| Staging | `https://dev-online-gateway.ghn.vn/shiip/public-api/v3/master-data/ward/all-by-province-id` |

**Method**: `GET`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `Token` | Yes | Your token (issued by GHN) — [get a token](https://developer.ghn.vn/en/docs/token/get-token.md) |
| `ShopId` | Yes | Shop ID (integer) |

## Parameters

- **province_id** (Int): 2-level-model province ID from [Get Province (New)](https://developer.ghn.vn/en/docs/master-data/get-province-new.md) (`_id` field). If missing or unknown, the API still returns HTTP 200 with `data` as `null` — treat empty `data` as a wrong province ID
- **offset** (Int): Pagination start position. Default: `0`
- **limit** (Int): Max items, at most `200`. The largest province is currently Ho Chi Minh City with 168 wards — a single `limit=200` call is enough

## Request Example

```bash
curl -X GET "https://dev-online-gateway.ghn.vn/shiip/public-api/v3/master-data/ward/all-by-province-id?province_id=1000001&offset=0&limit=200" \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837"
```

## Response

### Success (HTTP 200)

_Captured from a real Staging call with `province_id=1000001` (Ho Chi Minh City — trimmed to one of 168 wards, internal audit fields removed)._

```json
{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "_id": 1003646,
      "name": "Phường Vũng Tàu",
      "extension_names": [
        "phường vũng tàu",
        "p.vũng tàu",
        "vũng tàu",
        "vung tau",
        "phuong vung tau"
      ],
      "type": "ward",
      "parent_id": 1000001,
      "status": 1
    }
  ]
}
```

### Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]._id` | Int | 2-level-model ward ID (GHN's internal identifier) |
| `data[].name` | String | Canonical ward name — use verbatim as `to_ward_name` in [Create Order](https://developer.ghn.vn/en/docs/order/create.md) (new model) |
| `data[].extension_names` | String[] | Name variants (unaccented, abbreviated…) — useful for matching or suggesting as the user types |
| `data[].type` | String | Always `ward` |
| `data[].parent_id` | Int | ID of the province containing this ward (`_id` in [Get Province (New)](https://developer.ghn.vn/en/docs/master-data/get-province-new.md)) |
| `data[].status` | Int | `1` if active, `2` if disabled, `10` if deleted |

## Error Codes

| Condition | HTTP | Meaning |
| --- | --- | --- |
| `Authorization header is required!` | 401 | Missing `Token` |
| `data` is `null` | 200 | `province_id` missing or unknown (the API does not return a dedicated error) |
| IP not allowed | 401 | Your account has an IP whitelist and the request came from another IP |
| `SERVER_ERROR_COMMON` | 500 | System error |