> For the complete documentation index, see [llms.txt](https://shiply-integration-apis.gitbook.io/shiply-integration-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shiply-integration-apis.gitbook.io/shiply-integration-documentation/integration-apis/shipping-address/get-cities-and-villages.md).

# Get Cities And Villages

```php
POST /address/getCitiesAndVillages
```

This API is used to retrieve the list of cities and their associated villages within the Shiply system. These are utilized to define and select shipping addresses. 

#### Headers

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td>Accept</td><td>application/json</td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

#### Request body

{% code lineNumbers="true" %}

```json
{
    "Shiply_API_KEY": "your_api_key"
}
```

{% endcode %}

#### Response body

{% tabs %}
{% tab title="Success - Palestine" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
[
    {
        "id": 1,
        "name": "القدس",
        "deleted_at": null,
        "villages": [
            {
                "id": 331,
                "city_id": 1,
                "name": "القدس",
                "driver_region_id": null,
                "region_id": 2,
                "region_type": 2,
                "note": "يُرجى اختيار عنوان تفصيلي",
                "is_closed": 1,
                "deleted_at": null
            },
		................,
        ]
    },	
        ................,	
]
```

{% endcode %}

The API response returns an array of cities, where each city includes an array of its associated villages. Each city and village is represented by its name and ID.
{% endtab %}

{% tab title="Success - Jordan" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
[
     {
        "id": 9,
        "name": "عمان",
        "deleted_at": null,
        "villages": [
            {
                "id": 148,
                "city_id": 1,
                "name": "عمان",
                "region_id": 1,
                "region_type": 1,
                "note": "",
                "is_closed": 0,
                "deleted_at": null
            },
		................,
        ]
    },	
        ................,	
]
```

{% endcode %}

The API response returns an array of cities, where each city includes an array of its associated villages. Each city and village is represented by its name and ID.
{% endtab %}

{% tab title="Unauthorized" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "unauthorized"
    ]
}
```

{% endcode %}

This response is returned when the <mark style="color:blue;">Shiply\_API\_KEY</mark> is not included in the request body.
{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Recommendation:** We recommend using a dropdown list to allow users to select the city and village for the shipping address. For each selection, store the corresponding <mark style="color:blue;">city\_id</mark> and <mark style="color:blue;">village\_id</mark> to use them in subsequent operations.
{% endhint %}

#### Closed villages

As you can see in the API response, each village has certain values, such as <mark style="color:blue;">is\_closed</mark> and <mark style="color:blue;">note</mark>. The <mark style="color:blue;">is\_closed</mark> flag indicates whether Shiply can currently deliver parcels to that village. If <mark style="color:blue;">is\_closed</mark> is **1**, the village is closed for deliveries, otherwise, it is open and parcels can be delivered.

To handle closed villages in your integration, you have 2 choices:

* Filter the returned villages to exclude closed ones from the list.
* Display closed villages in the list but keep them disabled (so they cannot be selected as a shipping address). Also, show the village's note to indicate the reason for its closure.\
  \
  For example, in the response body provided earlier on this page, you can see that the village **"القدس"** is marked as closed, with a note saying **"يُرجى اختيار عنوان تفصيلي"**. This note guides the customer to select a specific village within the city of **"القدس"**.

  To display it in the list, format it as:\
  **"القدس، القدس (مغلقة - يُرجى اختيار عنوان تفصيلي)"** and ensure it is disabled.