# Suggest Province

> The Suggest Province endpoint provides predictive autocomplete and search for provinces, returning each match with its province code and Egon ID.

The Suggest Province endpoint provides predictive autocomplete and search for **provinces**, returning each match with its province code and Egon ID.

## Endpoint

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

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 province 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 | Territorial search container with parent identifier filter |
| `data.query` | String | Yes | Query string |
| `data.restrict_id` | Number | No | ID of the territorial level. Used for filtering the research by a certain territorial level |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/suggest/province" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"iso3":"ITA"},"data":{"query":"Ver"}}'
```

## Response

Matching province 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 |
| `data.results.province` | String | No | Province name |
| `data.results.province_code` | String | No | Province code |
| `data.results.province_id` | Number | No | ID of the province |
| `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 province candidates, administrative codes, and system status.

```json
{
  "data": {
    "results": [
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Piemonte",
        "region_id": 38000000002,
        "province": "Verbano Cusio Ossola",
        "province_code": "VB",
        "province_id": 38000000123
      },
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Piemonte",
        "region_id": 38000000002,
        "province": "Vercelli",
        "province_code": "VC",
        "province_id": 38000000112
      },
      {
        "iso3": "ITA",
        "lngout": "380",
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Veneto",
        "region_id": 38000000006,
        "province": "Verona",
        "province_code": "VR",
        "province_id": 38000000115
      }
    ]
  },
  "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"
  }
}
```