# Suggest House Number

> The Suggest House Number endpoint suggests house numbers for a street, including numbers with exponents and kilometer markers.

The Suggest House Number endpoint suggests **house numbers** for a street, including numbers with exponents and kilometer markers.

## Endpoint

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

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

Street ID context (`restrict_id`), house-number query, and options.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes | Processing parameters for house number search |
| `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` |
| `par.certified_only` | Boolean | No | Return only certified house numbers. Default: `false`. Default value: `false` |
| `data` | Object | Yes | Search container with mandatory street identifier for house number lookup |
| `data.restrict_id` | Number | Yes | ID of the street. Used for filtering the research by a certain street |
| `data.number` | Number | Yes | House number |

### Example request

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

## Response

Matching house numbers, exponents, parity, 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.number` | Number | No | House number |
| `data.results.exponent` | String | No | Exponent |
| `data.results.hn` | String | No | Formatted number |
| `data.results.hn_id` | Number | No | ID of the house number |
| `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 house numbers, exponents, parity, and system status.

```json
{
  "data": {
    "results": [
      {
        "number": "4",
        "hn": "4",
        "hn_id": 380100008326051
      },
      {
        "number": "4",
        "exponent": "A",
        "hn": "4 A",
        "hn_id": 380100008326039
      },
      {
        "number": "4",
        "exponent": "B",
        "hn": "4 B",
        "hn_id": 380100008326045
      },
      {
        "number": "4",
        "exponent": "C",
        "hn": "4 C",
        "hn_id": 380600052104491
      },
      {
        "number": "40",
        "hn": "40",
        "hn_id": 380100008326063
      },
      {
        "number": "40",
        "exponent": "A",
        "hn": "40 A",
        "hn_id": 380100008326057
      }
    ]
  },
  "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 number**

The number field is missing.

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

**HTTP 200: Missing restrict ID**

The restrict_id field is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "restrict_id 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"
  }
}
```