# COUNTRY-STATE-CITY

<mark style="color:blue;">`GET`</mark> `https://api.kosontechnology.com/country-state-city.php`

#### Path Parameters

| Name     | Type   | Description                                                       |
| -------- | ------ | ----------------------------------------------------------------- |
| country  | String | To specify the desired country.                                   |
| state    | String | to specify the desired state within the selected country.         |
| city     | String | To specify the desired city within the selected country and state |
| download | -      | To download the json file                                         |

{% hint style="info" %}
This API script is designed to retrieve information from the CountryStateCity API using provided parameters. The script constructs the appropriate URL based on the parameters provided and then fetches data from the API. Please follow the instructions below to use this script effectively.
{% endhint %}

## **Usage**

1. Making an HTTP request via a web browser or API Platform etc. [Postman](https://www.postman.com/).
2. The following parameters are accepted:

<table><thead><tr><th width="154.33333333333331">Name</th><th width="269">Description</th><th>Format</th></tr></thead><tbody><tr><td>country</td><td>To specify the desired country.</td><td><ul><li>ISO2 Code of Country</li><li><strong>'ALL'</strong> or <strong>'all'</strong></li></ul></td></tr><tr><td>state</td><td>To specify the desired state within the selected country.</td><td><ul><li>ISO2 Code of State</li><li><strong>'ALL'</strong> or <strong>'all'</strong></li></ul></td></tr><tr><td>city</td><td>To specify the desired city within the selected country and state.</td><td><ul><li><strong>'ALL'</strong> or <strong>'all'</strong></li></ul></td></tr><tr><td>download</td><td>To download the JSON output</td><td><ul><li>This parameter does not require the content, <strong>Leave empty</strong> or <strong>Type anything</strong> is acceptable</li></ul></td></tr></tbody></table>

3. Depending on the parameters provided, the script will construct a URL to fetch information from the CountryStateCity API.

## **Parameter Guidelines**

* **`country` Parameter:**
  * If you provide a `country` parameter as 'all' or 'ALL', the script will retrieve information about all countries.
  * If you specify a valid country ISO2 Code as the `country` parameter, the script will retrieve information about that specific country.
* **`state` Parameter:**
  * If you provide a `state` parameter as 'all' or 'ALL' in addition to the `country` parameter, the script will retrieve information about all states within the selected country.
  * If you specify a valid state ISO2 Code as the `state` parameter, the script will retrieve information about that specific state within the selected country.
* **`city` Parameter:**
  * If you provide a `city` parameter as 'all' or 'ALL' in addition to the `country` and `state` parameters, the script will retrieve information about all cities within the selected state and country.
* **`download` Parameter:**
  * If you want to download the JSON output of these parameter, define the parameter with empty or any input will able you to auto download it. See the download sample at [here](#download).

## ISO2 Code

Refer this [wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#QT) to find your ISO2 Code.

Below is a sample how to find Malaysia ISO2 Code:

1. Find Malaysia and you will see country code at the left column.

<figure><img src="https://3982209870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdwFjmPksROWsH7LWYXB2%2Fuploads%2Fgit-blob-a05205583f6f66bf14516567cc63bb5a07022ca3%2Fimage%20(1).png?alt=media" alt=""><figcaption><p>'MY' is Malaysia's ISO2 Code</p></figcaption></figure>

2. Onclick on the code then wikipedia with direct you to [ISO 3166-2:MY](https://en.wikipedia.org/wiki/ISO_3166-2:MY) where you can find its state code.

<figure><img src="https://3982209870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdwFjmPksROWsH7LWYXB2%2Fuploads%2Fgit-blob-a3966130c47a51c9e16ebd2e5604cba543b5f24e%2Fimage%20(2).png?alt=media" alt=""><figcaption><p>'01' is Johor's ISO2 Code</p></figcaption></figure>

## Demo

1. Retrieve information about all countries:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?country=ALL>" %}
Retrieve all countries data
{% endembed %}

2. Retrieve information about a specific country:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?country=MY>" %}
Retrieve Malaysia data
{% endembed %}

3. Retrieve information about all states:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?state=ALL>" %}
Retrieve all states data
{% endembed %}

4. Retrieve information about all states within a specific country:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?country=MY&state=ALL>" %}
Retrieve all state data from Malaysia
{% endembed %}

5. Retrieve information about a specific state within a specific country:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?country=MY&state=01>" %}
Retrieve Johor state data from Malaysia
{% endembed %}

6. Retrieve information about all cities within a specific state and country:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?city=ALL&country=MY&state=01>" %}
Retrieve all cities data from Malaysia's Johor
{% endembed %}

7. Retrieve information about all cities within a specific country:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?city=ALL&country=MY>" %}
Retrieve all cities data from Malaysia
{% endembed %}

## Download

Add `download` parameter to download the output json, below is some example of it:

{% embed url="<https://api.kosontechnology.com/country-state-city.php?country=MY&download=>" %}
Download Malaysia's Json File
{% endembed %}

{% embed url="<https://api.kosontechnology.com/country-state-city.php?city=all&country=my&download=&state=01>" %}
Download cities Json File from Malaysia's Johor
{% endembed %}