# Suggest Country

> The Suggest Country endpoint provides predictive autocomplete and search over world countries, with names in many languages, ISO codes, and Egon IDs.

The Suggest Country endpoint provides predictive autocomplete and search over **world countries**, with names in many languages, ISO codes, and Egon IDs.

## Endpoint

`POST https://{host}:{port}/Egon/api/suggest/country`

Replace `{host}` and `{port}` with the address of your Egon instance.

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | String | Yes | Authentication token sent in the `token` request header. |

## Request

Processing options, extraction limits, and country query.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | No | Processing parameters and output language for country search |
| `par.max_candidates` | Number | No | Maximum number of candidates to extract. Default value: `10` |
| `par.lngout` | String | No | Language code ISO 3166-1 numeric |
| `data` | Object | Yes | Query container holding the input search string |
| `data.query` | String | Yes | Query string |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/suggest/country" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":{"query":"Ital"}}'
```

## Response

Matching country candidates, ISO codes, and system status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No |  |
| `data.results` | Array | No | Array of candidate matches returned by the suggestion engine |
| `data.results.iso3` | String | No | Country code ISO 3166-1 alpha-3 |
| `data.results.lngout` | String | No | Language code ISO 3166-1 numeric |
| `data.results.country` | String | No | Country name |
| `data.results.country_id` | Number | No | ID of the country |
| `system` | Object | No | System error and execution status |
| `system.ret_code` | Number | No | Code: 0 no blocking error, <> 0 blocking error code |
| `system.des_ret_code` | String | No | Description |

### Example responses

**HTTP 200: Valid response**

Matching country candidates, ISO codes, and system status.

```json
{
  "data": {
    "results": [
      {
        "iso3": "ITA",
        "lngout": "792",
        "country": "İtalya",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "70",
        "country": "Italija",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "826",
        "country": "Italy",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "903",
        "country": "Italiya",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "908",
        "country": "Italiia",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "904",
        "country": "Itali",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "208",
        "country": "Italien",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "203",
        "country": "Itálie",
        "country_id": 38000000001
      },
      {
        "iso3": "ITA",
        "lngout": "470",
        "country": "Italja",
        "country_id": 38000000001
      }
    ]
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Missing data**

The data object is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "data not found"
  }
}
```

**HTTP 200: Missing query**

The query field is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "query not found"
  }
}
```

**HTTP 200: Missing token**

The token request header is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not found"
  }
}
```

**HTTP 200: Invalid token**

The token is invalid.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not valid"
  }
}
```