# Full Address

> The Full Address endpoint parses a complete address written as a single free-text string and returns a list of normalized candidate addresses.

The Full Address endpoint parses a complete address written as a single free-text string and returns a list of **normalized candidate addresses**.

## Endpoint

`POST https://{host}:{port}/Egon/api/single-line/full-address`

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

Single-line query string, country context, and parsing options.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes |  |
| `par.iso3` | String | Yes | ISO 3166-1 alpha-3 country code |
| `par.output` | String | No | Output language. Allowed values: `NAT`, `LAT`, `TRA`, `INT`, or an empty value to keep the input language |
| `data` | Object | Yes |  |
| `data.query` | String | Yes | Free-text query containing the complete address |
| `data.restrict_id` | Number | No | Identifier of the territorial restriction. Required when `restrict_level` is provided |
| `data.restrict_level` | String | No | Territorial level used for the restriction. Required when `restrict_id` is provided. Allowed values: `state`, `region`, `province`, `city`, `district1` |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/single-line/full-address" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"iso3":"ITA"},"data":{"query":"Via Pacinotti 4b, Verona"}}'
```

## Response

Structured address candidates, matching confidence scores, and system status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No |  |
| `data.results` | Array | No | Array of candidate matching addresses |
| `data.results.iso3` | String | No | ISO 3166-1 alpha-3 country code |
| `data.results.id` | Number | No | Street identifier |
| `data.results.country` | String | No | Country name |
| `data.results.state` | String | No | State name |
| `data.results.region` | String | No | Region name |
| `data.results.province` | String | No | Province name |
| `data.results.province_code` | String | No | Province code |
| `data.results.city` | String | No | City name |
| `data.results.district1` | String | No | First-level district name |
| `data.results.district2` | String | No | Second-level district name |
| `data.results.district3` | String | No | Third-level district name |
| `data.results.zipcode` | String | No | Postal or ZIP code |
| `data.results.street` | String | No | Street name |
| `data.results.hn_num` | String | No | Numeric portion of the house number |
| `data.results.hn_exp` | String | No | House-number suffix or exponent |
| `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**

Structured address candidates, matching confidence scores, and system status.

```json
{
  "data": {
    "results": [
      {
        "iso3": "ITA",
        "id": 38000073526,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Verona",
        "zipcode": "37135",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000330636,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Legnago",
        "zipcode": "37045",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000124342,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Cerea",
        "zipcode": "37053",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000175587,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Pescantina",
        "zipcode": "37026",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000315533,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Sommacampagna",
        "zipcode": "37066",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000328961,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Grezzana",
        "zipcode": "37023",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000176130,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Bardolino",
        "zipcode": "37011",
        "street": "Vicolo Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000124647,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "San Giovanni Lupatoto",
        "zipcode": "37057",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38000174082,
        "country": "Italia",
        "region": "Veneto",
        "province": "Verona",
        "city": "Valeggio sul Mincio",
        "zipcode": "37067",
        "street": "Via Antonio Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      },
      {
        "iso3": "ITA",
        "id": 38001153169,
        "country": "Italia",
        "region": "Lombardia",
        "province": "Brescia",
        "city": "Brescia",
        "zipcode": "25132",
        "street": "Via Pacinotti",
        "hn_num": "4",
        "hn_exp": "b"
      }
    ]
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Missing par**

The request is missing the required par object.

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

**HTTP 200: Invalid iso3**

The iso3 value is not a valid ISO 3166-1 alpha-3 country code.

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

**HTTP 200: Missing data**

The request is missing the required data object.

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

**HTTP 200: Missing query**

Provide a non-empty free-text address in the data.query field.

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

**HTTP 200: Missing token**

Provide the required authentication token in the token request header.

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

**HTTP 200: Invalid token**

The supplied token is invalid, expired, or not authorized for this service.

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