# Suggest Zipcode

> The Suggest Zipcode endpoint suggests postal codes at locality level (L) or at street level (S, available for GBR, IRL, NLD, and JPN).

The Suggest Zipcode endpoint suggests **postal codes** at locality level (`L`) or at street level (`S`, available for GBR, IRL, NLD, and JPN).

## Endpoint

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

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

Country context, extraction level, and postal code 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 | Search criteria for postal code lookup |
| `data.query` | String | Yes | Query string |
| `data.zip_level` | String | No | Extraction level: `L` for locality-level candidates, or `S` for street-level candidates. Street-level extraction is used in GBR, IRL, NLD, and JPN. Default: `L`. Default value: `L` |

### Example request

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

**Request body: Street level (GBR)**

Street-level extraction, which returns streets, buildings, and organizations for the postal code.

```json
{
  "par": {
    "iso3": "GBR"
  },
  "data": {
    "query": "SL0 9DL",
    "zip_level": "S"
  }
}
```

## Response

Matching postal codes, associated localities or streets, 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.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 |
| `data.results.city` | String | No | City name |
| `data.results.city_id` | Number | No | ID of the city |
| `data.results.district1` | String | No | First-level district name |
| `data.results.district1_id` | Number | No | ID of the first-level district |
| `data.results.street` | String | No | Street name |
| `data.results.street_id` | Number | No | ID of the street |
| `data.results.number` | String | No | House number |
| `data.results.exponent` | String | No | Exponent |
| `data.results.zipcode` | String | No | Postal code |
| `data.results.building` | String | No | Building name; available only for GBR and IRL |
| `data.results.subbuilding` | String | No | Sub-building information; available only for GBR and IRL |
| `data.results.organization` | String | No | Organization name; available only for GBR and IRL |
| `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 postal codes, associated localities or streets, and system status.

```json
{
  "data": {
    "results": [
      {
        "country": "Italia",
        "country_id": 38000000001,
        "region": "Veneto",
        "region_id": 38000000006,
        "province": "Verona",
        "province_id": 38000000115,
        "city": "Verona",
        "city_id": 38000004730,
        "zipcode": "37135"
      }
    ]
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Valid response, street level (GBR)**

Street-level candidates for a GBR postal code, with buildings and organizations, followed by the postal district.

```json
{
  "data": {
    "results": [
      {
        "state": "England",
        "province": "Buckinghamshire",
        "city": "Iver",
        "street": "NORTH PARK",
        "street_id": 82600826581,
        "zipcode": "SL0 9DL",
        "organization": "RICHINGS PARK GOLF CLUB"
      },
      {
        "state": "England",
        "province": "Buckinghamshire",
        "city": "Iver",
        "street": "NORTH PARK",
        "street_id": 82600826581,
        "zipcode": "SL0 9DL",
        "building": "HOME FARM COTTAGE"
      },
      {
        "state": "England",
        "province": "Buckinghamshire",
        "city": "Iver",
        "street": "NORTH PARK",
        "street_id": 82600826581,
        "zipcode": "SL0 9DL",
        "building": "THE PUMP HOUSE"
      },
      {
        "state": "England",
        "province": "Buckinghamshire",
        "city": "Iver",
        "street": "NORTH PARK",
        "street_id": 82600826581,
        "zipcode": "SL0 9DL",
        "building": "WEST GARDEN COTTAGE"
      },
      {
        "state": "England",
        "province": "Buckinghamshire",
        "city": "Iver",
        "street": "NORTH PARK",
        "street_id": 82600826581,
        "zipcode": "SL0 9DL",
        "building": "THE COTTAGE HOME FARM"
      },
      {
        "state": "England",
        "province": "Buckinghamshire",
        "city": "Iver",
        "city_id": 82600003273,
        "zipcode": "SL0"
      }
    ]
  },
  "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"
  }
}
```