# Address

> The Address endpoint validates and normalizes an address, returning the street, house number, postal data, Egon codes, and geographic coordinates.

## Endpoint

`POST https://{host}:{port}/Egon/api/norm`

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, processing options, and address fields to validate.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes | Processing options and country context for address validation. |
| `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.geo` | String | No | Activate geocoding. `N` No; `S` Yes. Default value: `N` |
| `par.fmtout` | String | No | Output format. `C` Capitalized; `M` Upper case; `T` Upper case with apostrophes instead of accents; `X` Upper case without accents. Default value: `C` |
| `par.fmtsht` | String | No | Activate short descriptions. `N` No; `S` Yes. Default value: `N` |
| `par.lngout` | String | No | Output language. `NAT` Native output language; `TRA` Transliterated output language; `INT` International or English output language; `<empty>` Keep the input language |
| `par.tpxout` | String | No | Output description format. `LAT` Latinized output without accents |
| `par.hn_code` | String | No | Activate Egon house-number codes. Default value: `S` |
| `data` | Object | Yes | Address information to validate |
| `data.address` | Object | Yes | Address information to validate. All individual address fields are optional. |
| `data.address.egoncode_place` | Number | No | Egon place code. |
| `data.address.egoncode_hn` | Number | No | Egon house-number code. |
| `data.address.country` | String | No | Country description. |
| `data.address.state` | String | No | State description. |
| `data.address.region` | String | No | Region description. |
| `data.address.province` | String | No | Province description. |
| `data.address.city` | String | No | City or municipality description. |
| `data.address.district1` | String | No | First district or locality description. |
| `data.address.district2` | String | No | Second district or locality description. |
| `data.address.district3` | String | No | Third district or locality description. |
| `data.address.zipcode` | String | No | Postal code. |
| `data.address.street_type` | String | No | Street type, for example Via, Viale, Piazza, or Corso. |
| `data.address.street` | String | No | Street description or street name. |
| `data.address.address` | String | No | Full unstructured address. |
| `data.address.hn` | String | No | House number. |
| `data.address.care_of` | String | No | Care-of information. |
| `data.address.building` | String | No | Building information. |
| `data.address.sub_building` | String | No | Sub-building information. |
| `data.address.organization` | String | No | Organization name. |
| `data.address.street_type_str2` | String | No | Second street type. |
| `data.address.street_2` | String | No | Second street description. |
| `data.address.hn_2` | String | No | Second house number. |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/norm" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"iso3":"ITA","geo":"S"},"data":{"address":{"city":"Verona","street":"Via pacinotti 4b"}}}'
```

## Response

Normalized address, geocoding coordinates, postal format, quality indicators, and system status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No | Normalized address data and optional output. |
| `data.name` | Object | No |  |
| `data.name.type_ana` | String | No | Name analysis type |
| `data.name.gender` | String | No | Gender |
| `data.name.full_name` | String | No | Full name |
| `data.name.last_name` | String | No | Separate surname |
| `data.name.mid_name` | String | No | Middle name |
| `data.name.first_name` | String | No | First name |
| `data.name.prename` | String | No | Separate name |
| `data.name.title` | String | No | Title |
| `data.name.firm_type` | String | No | Company legal form |
| `data.name.birth_date` | String | No | Date of birth |
| `data.name.birth_country` | String | No | Country of birth |
| `data.name.birth_province` | String | No | Province of birth |
| `data.name.birth_place` | String | No | Place of birth |
| `data.name.name_des` | String | No | Name description |
| `data.name.status` | String | No | Validation status |
| `data.tax_code` | Object | No |  |
| `data.tax_code.cod_description` | String | No | Code description |
| `data.vat_number` | Object | No |  |
| `data.vat_number.cod_description` | String | No | Code description |
| `data.address` | Object | No | Normalized address result. |
| `data.address.standard` | Object | No | Complete structured and normalized address. |
| `data.address.standard.iso2` | String | No | Country ISO 3166-1 alpha-2 code. |
| `data.address.standard.iso3` | String | No | Country ISO 3166-1 alpha-3 code. |
| `data.address.standard.country` | String | No | Normalized country description. |
| `data.address.standard.country_lng` | String | No | Country language code. |
| `data.address.standard.state` | String | No | Normalized state description. |
| `data.address.standard.state_code` | String | No | State code. |
| `data.address.standard.state_lng` | String | No | State language code. |
| `data.address.standard.region` | String | No | Normalized region description. |
| `data.address.standard.region_code` | String | No | Region code. |
| `data.address.standard.region_lng` | String | No | Region language code. |
| `data.address.standard.province` | String | No | Normalized province description. |
| `data.address.standard.province_code` | String | No | Province code. |
| `data.address.standard.province_lng` | String | No | Province language code. |
| `data.address.standard.city` | String | No | Normalized city description. |
| `data.address.standard.city_lng` | String | No | City language code. |
| `data.address.standard.locality` | String | No | Normalized locality or district description. |
| `data.address.standard.locality_lng` | String | No | Locality language code. |
| `data.address.standard.locality2` | String | No | Second locality or district description. |
| `data.address.standard.locality2_lng` | String | No | Second locality language code. |
| `data.address.standard.locality3` | String | No | Third locality or district description. |
| `data.address.standard.locality3_lng` | String | No | Third locality language code. |
| `data.address.standard.zipcode` | String | No | Normalized postal code. |
| `data.address.standard.street_type` | String | No | Normalized street-type description. |
| `data.address.standard.street_name` | String | No | Normalized street name. |
| `data.address.standard.street` | String | No | Normalized street type and name. |
| `data.address.standard.street_lng` | String | No | Street language code. |
| `data.address.standard.address` | String | No | Formatted street address and house number. |
| `data.address.standard.full_address` | String | No | Complete normalized address. |
| `data.address.standard.street_type2` | String | No | Second street-type description. |
| `data.address.standard.street_name2` | String | No | Second street name. |
| `data.address.standard.street2` | String | No | Second normalized street. |
| `data.address.standard.street2_lng` | String | No | Second street language code. |
| `data.address.standard.hn` | String | No | Normalized house number. |
| `data.address.standard.hn_ext` | String | No | Additional house-number information. |
| `data.address.standard.care_of` | String | No | Care-of information. |
| `data.address.standard.hn_2` | String | No | Second house number. |
| `data.address.standard.building` | String | No | Building information. |
| `data.address.standard.subbuilding` | String | No | Sub-building information. |
| `data.address.standard.organization` | String | No | Organization |
| `data.address.standard.postal_town1` | String | No | Primary postal town or area. |
| `data.address.standard.postal_town2` | String | No | Secondary postal town or locality. |
| `data.address.standard.match_code` | String | No | Address matching result code. |
| `data.address.standard.adm_code` | Array | No | Administrative code collection. |
| `data.address.standard.adm_code.iso3` | String | No | Country ISO alpha-3 code. |
| `data.address.standard.adm_code.type` | String | No | Administrative-code type. |
| `data.address.standard.adm_code.value` | String | No | Administrative code or description. |
| `data.address.standard.cnd` | Array | No | Candidate address values when matching is not exact. |
| `data.address.standard.cnd.province` | String | No | Candidate province. |
| `data.address.standard.cnd.city` | String | No | Candidate city. |
| `data.address.standard.cnd.locality` | String | No | Candidate locality. |
| `data.address.standard.cnd.street` | String | No | Candidate street. |
| `data.address.standard.cnd.zipcode` | String | No | Candidate postal code. |
| `data.address.standard.cnd.street_code` | Number | No | Candidate street code. |
| `data.address.standard.egon_code` | Object | No | Egon hierarchical code collection. |
| `data.address.standard.egon_code.city` | Number | No | Egon city code. |
| `data.address.standard.egon_code.locality` | Number | No | Egon locality code. |
| `data.address.standard.egon_code.street` | Number | No | Egon street code. |
| `data.address.standard.egon_code.hn` | Number | No | Egon house-number code. |
| `data.address.short` | Object | No | Short descriptions, returned when par.fmtsht is enabled. |
| `data.address.short.country` | String | No | Country description. |
| `data.address.short.state` | String | No | State description. |
| `data.address.short.region` | String | No | Region description. |
| `data.address.short.province` | String | No | Province description. |
| `data.address.short.city` | String | No | City description. |
| `data.address.short.locality` | String | No | Locality or district description. |
| `data.address.short.locality2` | String | No | Second locality description. |
| `data.address.short.locality3` | String | No | Third locality description. |
| `data.address.short.street_type` | String | No | Street-type description. |
| `data.address.short.street_name` | String | No | Street name. |
| `data.address.short.street` | String | No | Street type and name. |
| `data.address.smart` | Object | No | Simplified address representation. |
| `data.address.smart.country` | String | No | Country description |
| `data.address.smart.administrative_level` | String | No | Administrative level. |
| `data.address.smart.city` | String | No | City. |
| `data.address.smart.address` | String | No | Street type + Street description + House number |
| `data.address.smart.zipcode` | String | No | Postal code. |
| `data.geo` | Object | No | Geocoding output, returned when par.geo is set to S. |
| `data.geo.lat_long` | String | No | Coordinates in latitude, longitude format. |
| `data.geo.geo_level` | String | No | Geocoding quality level. |
| `data.geo.census_code` | String | No | Census code. |
| `data.geo.census_lat_long` | String | No | Census coordinates. |
| `data.postal` | Object | No | Postal-format output rows. |
| `data.postal.row1` | String | No | Postal row 1. |
| `data.postal.row2` | String | No | Postal row 2. |
| `data.postal.row3` | String | No | Postal row 3. |
| `data.postal.row4` | String | No | Postal row 4. |
| `data.postal.row5` | String | No | Postal row 5. |
| `data.postal.row6` | String | No | Postal row 6. |
| `data.postal.row7` | String | No | Postal row 7. |
| `data.phones` | Array | No | Phone numbers to validate |
| `data.phones.iso3` | String | No | Country code (ISO 3166-1 alpha-3) |
| `data.phones.type` | String | No | Administrative-code type |
| `data.phones.pre_int` | String | No | International telephone prefix |
| `data.phones.pre_nat` | String | No | National telephone prefix |
| `data.phones.number` | String | No | Telephone number |
| `data.emails` | Array | No | Email addresses to validate |
| `data.emails.email` | String | No | Email address |
| `data.codes` | Array | No | Administrative and cadastral domain codes |
| `data.codes.type` | String | No | Administrative-code type |
| `data.codes.cod_description` | String | No | Code description |
| `quality` | Object | No | Address validation quality indicators. |
| `quality.phones` | Array | No | Phone numbers to validate |
| `quality.phones.flag` | String | No | Quality flag |
| `quality.phones.code` | Number | No | Quality code |
| `quality.phones.description` | String | No | Human-readable quality description |
| `quality.emails` | Array | No | Email addresses to validate |
| `quality.emails.flag` | String | No | Quality flag |
| `quality.emails.code` | Number | No | Quality code |
| `quality.emails.description` | String | No | Human-readable quality description |
| `quality.tax_code` | Object | No |  |
| `quality.tax_code.flag` | String | No | Quality flag |
| `quality.tax_code.code` | Number | No | Quality code |
| `quality.tax_code.description` | String | No | Human-readable quality description |
| `quality.name` | Object | No |  |
| `quality.name.person` | Object | No |  |
| `quality.name.person.flag` | String | No | Quality flag |
| `quality.name.person.code` | Number | No | Quality code |
| `quality.name.person.description` | String | No | Human-readable quality description |
| `quality.name.birth_date` | Object | No |  |
| `quality.name.birth_date.flag` | String | No | Quality flag |
| `quality.name.birth_date.code` | Number | No | Quality code |
| `quality.name.birth_date.description` | String | No | Human-readable quality description |
| `quality.name.birth_place` | Object | No |  |
| `quality.name.birth_place.flag` | String | No | Quality flag |
| `quality.name.birth_place.code` | Number | No | Quality code |
| `quality.name.birth_place.description` | String | No | Human-readable quality description |
| `quality.address` | Object | No | Quality results by address component. |
| `quality.address.locality` | Object | No | Quality of locality or city matching. |
| `quality.address.locality.flag` | String | No | Quality flag. |
| `quality.address.locality.code` | Number | No | Quality code. |
| `quality.address.locality.description` | String | No | Human-readable quality result. |
| `quality.address.street` | Object | No | Quality of street matching. |
| `quality.address.street.flag` | String | No | Quality flag. |
| `quality.address.street.code` | Number | No | Quality code. |
| `quality.address.street.description` | String | No | Human-readable quality result. |
| `quality.address.hn` | Object | No | Quality of house-number matching. |
| `quality.address.hn.flag` | String | No | Quality flag. |
| `quality.address.hn.code` | Number | No | Quality code. |
| `quality.address.hn.description` | String | No | Human-readable quality result. |
| `quality.vat_number` | Object | No |  |
| `quality.vat_number.flag` | String | No | Quality flag |
| `quality.vat_number.code` | Number | No | Quality code |
| `quality.vat_number.description` | String | No | Human-readable quality description |
| `system` | Object | No | Request processing status. |
| `system.ret_code` | Number | No | Processing result code. 0 means no blocking error. |
| `system.des_ret_code` | String | No | Human-readable processing result. |

### Example responses

**HTTP 200: Valid response**

The address was processed successfully. Returns normalized address levels, geocoding coordinates, and quality flags.

```json
{
  "data": {
    "address": {
      "standard": {
        "iso2": "IT",
        "iso3": "ITA",
        "country": "Italia",
        "country_lng": "380",
        "region": "Veneto",
        "region_lng": "380",
        "province": "Verona",
        "province_code": "VR",
        "province_lng": "380",
        "city": "Verona",
        "city_lng": "380",
        "zipcode": "37135",
        "street_type": "Via",
        "street_name": "Antonio Pacinotti",
        "street": "Via Antonio Pacinotti",
        "street_lng": "380",
        "address": "Via Antonio Pacinotti,4/B",
        "full_address": "Via Antonio Pacinotti,4/B, Verona, VR, Veneto, 37135, Italia",
        "hn": "4/B",
        "postal_town1": "VERONA",
        "match_code": "3800000473038000073526000000004000000000",
        "adm_code": [
          {
            "iso3": "ITA",
            "type": "50137",
            "value": "VR"
          },
          {
            "iso3": "ITA",
            "type": "30000",
            "value": "L781"
          },
          {
            "iso3": "ITA",
            "type": "30021",
            "value": "023091"
          },
          {
            "iso3": "ITA",
            "type": "30022",
            "value": "005"
          },
          {
            "iso3": "ITA",
            "type": "30030",
            "value": "11700"
          },
          {
            "iso3": "ITA",
            "type": "30050",
            "value": "0777000"
          },
          {
            "iso3": "ITA",
            "type": "30060",
            "value": "086"
          },
          {
            "iso3": "ITA",
            "type": "30061",
            "value": "660999"
          },
          {
            "iso3": "ITA",
            "type": "30070",
            "value": "ITA"
          },
          {
            "iso3": "ITA",
            "type": "30071",
            "value": "IT"
          },
          {
            "iso3": "ITA",
            "type": "30072",
            "value": "380"
          },
          {
            "iso3": "ITA",
            "type": "30114",
            "value": "ITALIA"
          }
        ],
        "egon_code": {
          "city": 38000004730,
          "street": 38000073526,
          "hn": 380100008326045
        }
      },
      "smart": {
        "country": "Italia",
        "administrative_level": "Verona",
        "city": "Verona",
        "address": "Via Antonio Pacinotti,4/B",
        "zipcode": "37135"
      }
    },
    "geo": {
      "lat_long": "45.40616800, 10.97379600",
      "geo_level": "A41-111",
      "census_code": "0230910000922",
      "census_lat_long": "45.40753707, 10.97251045"
    },
    "postal": {
      "row4": "VIA ANTONIO PACINOTTI 4/B",
      "row5": "37135 VERONA VR"
    }
  },
  "quality": {
    "address": {
      "locality": {
        "flag": "0",
        "code": 0,
        "description": "Ok"
      },
      "street": {
        "flag": "1",
        "code": 801,
        "description": "Candidato strada con parole in meno"
      },
      "hn": {
        "flag": "0",
        "code": 0,
        "description": "Ok"
      }
    }
  },
  "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: 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 request is missing the required data object.

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