# Suggest Region

> The Suggest Region endpoint provides predictive autocomplete and search for regions, returning each matching region with its name and Egon ID.

The Suggest Region endpoint provides predictive autocomplete and search for **regions**, returning each matching region with its name and Egon ID.

## Endpoint

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

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, country context, and region search query.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes | Processing parameters, candidate limits, and country context |
| `par.iso2` | String | No | Country code, ISO 3166-1 alpha-2. One of `iso2` or `iso3` is **required**. |
| `par.iso3` | String | No | Country code, ISO 3166-1 alpha-3. One of `iso2` or `iso3` is **required**. |
| `par.max_candidates` | Number | No | Maximum number of candidates to extract. Default value: `10` |
| `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/region" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"iso3":"ITA"},"data":{"query":"v"}}'
```

## Response

Matching region candidates, administrative 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 |
| `data.results.state` | String | No | State name |
| `data.results.state_code` | String | No | State code |
| `data.results.state_id` | Number | No | ID of the state |
| `data.results.region` | String | No | Region name |
| `data.results.region_code` | String | No | Region code |
| `data.results.region_id` | Number | No | ID of the region |
| `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 region candidates, administrative codes, and system status.

```json
{
  "data": {
    "results": [
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Valle d'Aosta",
        "region_id": 38000000003
      },
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Veneto",
        "region_id": 38000000006
      },
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Friuli-Venezia Giulia",
        "region_id": 38000000007
      }
    ]
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Missing par**

The par object is missing.

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

**HTTP 200: Missing iso2 and iso3**

Iso2 or Iso3 field is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "iso2 or iso3 parameter not found"
  }
}
```

**HTTP 200: Invalid iso2**

The iso2 value is not valid.

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

**HTTP 200: Invalid iso3**

The iso3 value is not valid.

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

**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"
  }
}
```