# Egon Docs > Verify, correct, and complete addresses in real time, with a single API. This file contains all documentation content in a single document following the llmstxt.org standard. ## Egon API Reference Suggest, validate, and normalize addresses and related data. Every service is a `POST` endpoint that accepts and returns JSON. ### Base URL - Default: `https://{host}:{port}/Egon`. Replace `{host}` and `{port}` with the address of your Egon instance. - `/api/routes`: `https://{host}:{port}/EgonMbk`. Replace `{host}` and `{port}` with the address of your Egon Map Broker instance. ### Authentication Authentication token sent in the `token` request header. ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/country" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"data":{"query":"Ital"}}' ``` ### Services #### Suggest Services Predictive autocomplete for countries, cities, streets, postal codes, and house numbers. Results update as you type, so users enter valid addresses. - [Suggest Country](https://documentation.egon.com/docs/api/country.md): The Suggest Country endpoint provides predictive autocomplete and search over world countries, with names in many languages, ISO codes, and Egon IDs. (`POST /api/suggest/country`) - [Suggest State](https://documentation.egon.com/docs/api/state.md): The Suggest State endpoint provides predictive autocomplete and search for states and federal states, returning names, codes, and Egon IDs. (`POST /api/suggest/state`) - [Suggest Region](https://documentation.egon.com/docs/api/region.md): The Suggest Region endpoint provides predictive autocomplete and search for regions, returning each matching region with its name and Egon ID. (`POST /api/suggest/region`) - [Suggest Province](https://documentation.egon.com/docs/api/province.md): The Suggest Province endpoint provides predictive autocomplete and search for provinces, returning each match with its province code and Egon ID. (`POST /api/suggest/province`) - [Suggest City](https://documentation.egon.com/docs/api/city.md): The Suggest City endpoint provides predictive autocomplete and search for cities and municipalities, with their postal code and Egon ID. (`POST /api/suggest/city`) - [Suggest District 1](https://documentation.egon.com/docs/api/district-1.md): The Suggest District 1 endpoint provides predictive autocomplete and search for first-level districts, such as localities and municipalities. (`POST /api/suggest/district1`) - [Suggest Zipcode](https://documentation.egon.com/docs/api/zipcode.md): The Suggest Zipcode endpoint suggests postal codes at locality level (L) or at street level (S, available for GBR, IRL, NLD, and JPN). (`POST /api/suggest/zipcode`) - [Suggest Zipcode All](https://documentation.egon.com/docs/api/zipcode-all.md): The Suggest Zipcode All endpoint returns every house-number range for a city, street, or house number, with its parity and range type. (`POST /api/suggest/zipcodeAll`) - [Suggest Street](https://documentation.egon.com/docs/api/street.md): The Suggest Street endpoint provides predictive autocomplete for street search. (`POST /api/suggest/street`) - [Suggest House Number](https://documentation.egon.com/docs/api/hn.md): The Suggest House Number endpoint suggests house numbers for a street, including numbers with exponents and kilometer markers. (`POST /api/suggest/hn`) - [Suggest Birth Locality](https://documentation.egon.com/docs/api/birth-locality.md): The Suggest Birth Locality endpoint searches official and historical birth localities and returns the corresponding Belfiore code. (`POST /api/suggest/birthLocality`) #### Validation Services Validation and normalization of addresses, names, phones, emails, tax codes, and VAT numbers. Every result has quality flags and codes. - [Address](https://documentation.egon.com/docs/api/address.md): The Address endpoint validates and normalizes an address, returning the street, house number, postal data, Egon codes, and geographic coordinates. (`POST /api/norm`) - [Email](https://documentation.egon.com/docs/api/email.md): Validate one or more email addresses and return normalized values together with syntax and domain quality indicators. (`POST /api/norm`) - [Name](https://documentation.egon.com/docs/api/name.md): Validate personal names, sole proprietorships, company names, co-holder names, and family surnames, and return normalized and structured output. (`POST /api/norm`) - [Phone](https://documentation.egon.com/docs/api/phone.md): Validate and normalize telephone numbers provided either as individual international and national prefix components or as a single full number. (`POST /api/norm`) - [Tax Code Calculation](https://documentation.egon.com/docs/api/tax-code-calc.md): Calculate an Italian tax code (Codice Fiscale) from surname, name, gender, date of birth, and city of birth, with a quality flag for the result. (`POST /api/norm`) - [Tax Code Validation](https://documentation.egon.com/docs/api/tax-code-check.md): Check the formal validity and structure of an Italian tax code (Codice Fiscale) and get a quality flag and code that describe the result. (`POST /api/norm`) - [Tax Code Extraction](https://documentation.egon.com/docs/api/tax-code-extract.md): Extract gender, date of birth, and place of birth (city and province) from an Italian tax code (Codice Fiscale), with a quality flag. (`POST /api/norm`) - [Tax Code Verification](https://documentation.egon.com/docs/api/tax-code-match.md): Compare a tax code against a person's identifying data, including name, gender, date of birth, and birthplace. (`POST /api/norm`) - [VAT Validation](https://documentation.egon.com/docs/api/vat-check.md): Check the structure and formal validity of a VAT number (Partita IVA) and get a quality flag and code that describe the result of the check. (`POST /api/norm`) - [VAT Extraction](https://documentation.egon.com/docs/api/vat-ext.md): Validate and enrich company data from a VAT number: official business name, legal address, phone numbers, PEC email, and ATECO codes. (`POST /api/norm`) #### Single Line Service Recognition and normalization of a complete address written as a single free-text string. Returns a list of normalized candidates to choose from. - [Full Address](https://documentation.egon.com/docs/api/full-address.md): The Full Address endpoint parses a complete address written as a single free-text string and returns a list of normalized candidate addresses. (`POST /api/single-line/full-address`) #### Reverse Geocoding Conversion of geographic coordinates into normalized addresses. Returns the nearest house numbers with street, postal code, and distance. - [Address from Coordinates](https://documentation.egon.com/docs/api/reverse.md): The Reverse geocoding service retrieves address candidates from geographic coordinates, with street, house number, postal code, and distance. (`POST /api/revGeo`) #### Map Broker Services Route calculation and distance matrix services. The Routing endpoint calculates routes for a generic vehicle or for pedestrians. - [Routing](https://documentation.egon.com/docs/api/routing.md): Calculate a route between an origin and a destination for a generic vehicle or a pedestrian, based on the HERE Routing API v8. (`POST /api/routes`) ### Reference - [Quality Indicators](https://documentation.egon.com/docs/quality-indicators.md): Detailed validation flags (0, 1, 2/3) and outcome codes for addresses, geocoding, tax codes, and VAT. - [Domains & Dictionaries](https://documentation.egon.com/docs/domains.md): Standardized domain codes used in request and response fields (administrative codes, person types, phone lines). ### OpenAPI schema The full OpenAPI 3.1.0 schema is available at https://documentation.egon.com/openapi.json and https://documentation.egon.com/openapi.yaml. Per-family specifications are available under `https://documentation.egon.com/openapi/.{json,yaml}`. ### Help & Support Need assistance with integration, enterprise licensing, or technical inquiries? Our team and resources are at your service. - [Egon Website](https://www.egon.com/): Discover Egon's suite of enterprise data-quality solutions, customer success stories, and product capabilities. - [Contact Us!](https://www.egon.com/company/contact-us): Get in touch with our engineering and integration team to learn more about our services and request dedicated support. --- ## Suggest Services Predictive autocomplete for countries, cities, streets, postal codes, and house numbers. Results update as you type, so users enter valid addresses. OpenAPI contract: [JSON](https://documentation.egon.com/openapi/suggest-services.json) · [YAML](https://documentation.egon.com/openapi/suggest-services.yaml) ### Endpoints - [Suggest Country](https://documentation.egon.com/docs/api/country.md): The Suggest Country endpoint provides predictive autocomplete and search over world countries, with names in many languages, ISO codes, and Egon IDs. (`POST /api/suggest/country`) - [Suggest State](https://documentation.egon.com/docs/api/state.md): The Suggest State endpoint provides predictive autocomplete and search for states and federal states, returning names, codes, and Egon IDs. (`POST /api/suggest/state`) - [Suggest Region](https://documentation.egon.com/docs/api/region.md): The Suggest Region endpoint provides predictive autocomplete and search for regions, returning each matching region with its name and Egon ID. (`POST /api/suggest/region`) - [Suggest Province](https://documentation.egon.com/docs/api/province.md): The Suggest Province endpoint provides predictive autocomplete and search for provinces, returning each match with its province code and Egon ID. (`POST /api/suggest/province`) - [Suggest City](https://documentation.egon.com/docs/api/city.md): The Suggest City endpoint provides predictive autocomplete and search for cities and municipalities, with their postal code and Egon ID. (`POST /api/suggest/city`) - [Suggest District 1](https://documentation.egon.com/docs/api/district-1.md): The Suggest District 1 endpoint provides predictive autocomplete and search for first-level districts, such as localities and municipalities. (`POST /api/suggest/district1`) - [Suggest Zipcode](https://documentation.egon.com/docs/api/zipcode.md): The Suggest Zipcode endpoint suggests postal codes at locality level (L) or at street level (S, available for GBR, IRL, NLD, and JPN). (`POST /api/suggest/zipcode`) - [Suggest Zipcode All](https://documentation.egon.com/docs/api/zipcode-all.md): The Suggest Zipcode All endpoint returns every house-number range for a city, street, or house number, with its parity and range type. (`POST /api/suggest/zipcodeAll`) - [Suggest Street](https://documentation.egon.com/docs/api/street.md): The Suggest Street endpoint provides predictive autocomplete for street search. (`POST /api/suggest/street`) - [Suggest House Number](https://documentation.egon.com/docs/api/hn.md): The Suggest House Number endpoint suggests house numbers for a street, including numbers with exponents and kilometer markers. (`POST /api/suggest/hn`) - [Suggest Birth Locality](https://documentation.egon.com/docs/api/birth-locality.md): The Suggest Birth Locality endpoint searches official and historical birth localities and returns the corresponding Belfiore code. (`POST /api/suggest/birthLocality`) --- ## Suggest Country The Suggest Country endpoint provides predictive autocomplete and search over **world countries**, with names in many languages, ISO codes, and Egon IDs. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/country` 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, extraction limits, and country query. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | No | Processing parameters and output language for country search | | `par.max_candidates` | Number | No | Maximum number of candidates to extract. Default value: `10` | | `par.lngout` | String | No | Language code ISO 3166-1 numeric | | `data` | Object | Yes | Query container holding the input search string | | `data.query` | String | Yes | Query string | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/country" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"data":{"query":"Ital"}}' ``` ### Response Matching country candidates, ISO 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 | | `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 country candidates, ISO codes, and system status. ```json { "data": { "results": [ { "iso3": "ITA", "lngout": "792", "country": "İtalya", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "70", "country": "Italija", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "826", "country": "Italy", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "903", "country": "Italiya", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "908", "country": "Italiia", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "904", "country": "Itali", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "208", "country": "Italien", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "203", "country": "Itálie", "country_id": 38000000001 }, { "iso3": "ITA", "lngout": "470", "country": "Italja", "country_id": 38000000001 } ] }, "system": { "ret_code": 0, "des_ret_code": "Ok" } } ``` **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" } } ``` --- ## Suggest State The Suggest State endpoint provides predictive autocomplete and search for **states and federal states**, returning names, codes, and Egon IDs. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/state` 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 state 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 | Query container holding the input search string | | `data.query` | String | Yes | Query string | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/state" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"USA"},"data":{"query":"ma"}}' ``` ### Response Matching state 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 | | `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 state candidates, administrative codes, and system status. ```json { "data": { "results": [ { "iso3": "USA", "lngout": "840", "country": "United States", "country_id": 84000000001, "state": "Massachusetts", "state_code": "MA", "state_id": 84000000027 }, { "iso3": "USA", "lngout": "840", "country": "United States", "country_id": 84000000001, "state": "Maine", "state_code": "ME", "state_id": 84000000029 }, { "iso3": "USA", "lngout": "840", "country": "United States", "country_id": 84000000001, "state": "Marshall Islands", "state_code": "MH", "state_id": 84000000030 }, { "iso3": "USA", "lngout": "840", "country": "United States", "country_id": 84000000001, "state": "Maryland", "state_code": "MD", "state_id": 84000000028 }, { "iso3": "USA", "lngout": "840", "country": "United States", "country_id": 84000000001, "state": "Northern Mariana Islands", "state_code": "MP", "state_id": 84000000034 } ] }, "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" } } ``` --- ## Suggest Region The Suggest Region endpoint provides predictive autocomplete and search for **regions**, returning each matching region with its name and Egon ID. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/region` 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 region 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 | Query container holding the input search string | | `data.query` | String | Yes | Query string | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/region" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"ITA"},"data":{"query":"v"}}' ``` ### Response Matching region 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 | | `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 region candidates, administrative codes, and system status. ```json { "data": { "results": [ { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38000000001, "region": "Valle d'Aosta", "region_id": 38000000003 }, { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38000000001, "region": "Veneto", "region_id": 38000000006 }, { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38000000001, "region": "Friuli-Venezia Giulia", "region_id": 38000000007 } ] }, "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" } } ``` --- ## Suggest Province 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" } } ``` --- ## Suggest City The Suggest City endpoint provides predictive autocomplete and search for **cities and municipalities**, with their postal code and Egon ID. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/city` 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 city 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/city" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"ITA"},"data":{"query":"Roveredo"}}' ``` ### Response Matching city candidates, administrative hierarchy, 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 | | `data.results.city` | String | No | City name | | `data.results.city_id` | Number | No | ID of the city | | `data.results.zipcode` | String | No | Postal code | | `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 city candidates, administrative hierarchy, and system status. ```json { "data": { "results": [ { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38000000001, "region": "Friuli-Venezia Giulia", "region_id": 38000000007, "province": "Pordenone", "province_code": "PN", "province_id": 38000000082, "city": "Roveredo in Piano", "city_id": 38000004347, "zipcode": "33080" }, { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38000000001, "region": "Veneto", "region_id": 38000000006, "province": "Verona", "province_code": "VR", "province_id": 38000000115, "city": "Roveredo di Guà", "city_id": 38000004686, "zipcode": "37040" } ] }, "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" } } ``` --- ## Suggest District 1 The Suggest District 1 endpoint provides predictive autocomplete and search for **first-level districts**, such as localities and municipalities. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/district1` 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, city ID context, and district 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/district1" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"ITA"},"data":{"query":"Rovaio"}}' ``` ### Response Matching district candidates, administrative hierarchy, 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 | | `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.zipcode` | String | No | Postal code | | `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 district candidates, administrative hierarchy, and system status. ```json { "data": { "results": [ { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38001476230, "region": "Emilia-Romagna", "region_id": 38000000009, "province": "Piacenza", "province_code": "PC", "province_id": 38000000077, "city": "Corte Brugnatella", "city_id": 38000003969, "district1": "Rovaiola", "district1_id": 38001476230, "zipcode": "29020" }, { "iso3": "ITA", "lngout": "380", "country": "Italia", "country_id": 38001468884, "region": "Lombardia", "region_id": 38000000004, "province": "Pavia", "province_code": "PV", "province_id": 38000000086, "city": "Brallo di Pregola", "city_id": 38000003739, "district1": "Rovaiolo", "district1_id": 38001468884, "zipcode": "27050" } ] }, "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" } } ``` --- ## 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). ### 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" } } ``` --- ## Suggest Zipcode All The Suggest Zipcode All endpoint returns every **house-number range** for a city, street, or house number, with its parity and range type. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/zipcodeAll` 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, entity ID, and house-number parameters. | 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 full postal code lookup | | `data.city_id` | Number | No | ID of the city | | `data.street_id` | Number | No | ID of the street | | `data.hn` | Number | No | House number | | `data.zipcode` | String | No | Postal code | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/zipcodeAll" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"ITA"},"data":{"street_id":"38000093621"}}' ``` ### Response House-number range results, parity codes, postal 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.zipcode` | String | No | Postal code | | `data.results.hn_start` | String | No | Range starting house number | | `data.results.hn_end` | String | No | Range ending house number | | `data.results.exp_start` | String | No | Range starting exponent | | `data.results.exp_end` | String | No | Range ending exponent | | `data.results.parity` | String | No | Parity: `E` for even and `O` for odd | | `data.results.range_type` | String | No | Range type: `0` for house number and `2` for kilometer indication | | `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** House-number range results, parity codes, postal codes, and system status. ```json { "data": { "results": [ { "zipcode": "20124", "hn_start": "2", "hn_end": "80", "parity": "E", "range_type": "0" }, { "zipcode": "20125", "hn_start": "90", "hn_end": "132", "parity": "E", "range_type": "0" }, { "zipcode": "20159", "hn_start": "1", "hn_end": "147", "parity": "O", "range_type": "0" } ] }, "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 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" } } ``` --- ## Suggest Street The Suggest Street endpoint provides predictive autocomplete for **street search**. The `restrict_id` parameter (city ID) is required. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/street` 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 City context (`restrict_id`), street query, and output options. | 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 container with mandatory parent territorial identifier | | `data.query` | String | Yes | Query string | | `data.restrict_id` | Number | Yes | ID of the city. Used for filtering the research by a certain territorial level | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/street" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"ITA"},"data":{"query":"Via Pac","restrict_id":38000004730}}' ``` ### Response Matching street candidates, street 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.lngout` | String | No | Language code ISO 3166-1 numeric | | `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.zipcode` | String | No | Postal code | | `data.results.street` | String | No | Street name | | `data.results.street_id` | Number | No | ID of the street | | `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 street candidates, street codes, and system status. ```json { "data": { "results": [ { "lngout": "380", "region": "Veneto", "region_id": 38000000006, "province": "Verona", "province_code": "VR", "province_id": 38000000115, "city": "Verona", "city_id": 38000004730, "zipcode": "37135", "street": "Via Antonio Pacinotti", "street_id": 38000073526 }, { "lngout": "380", "region": "Veneto", "region_id": 38000000006, "province": "Verona", "province_code": "VR", "province_id": 38000000115, "city": "Verona", "city_id": 38000004730, "zipcode": "37124", "street": "Via della Pace", "street_id": 38000073960 } ] }, "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 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" } } ``` --- ## Suggest House Number 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" } } ``` --- ## Suggest Birth Locality The Suggest Birth Locality endpoint searches official and historical **birth localities** and returns the corresponding Belfiore code. ### Endpoint `POST https://{host}:{port}/Egon/api/suggest/birthLocality` 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 Search query and optional birth date filtering. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Processing parameters for birth locality search | | `par.function` | String | No | Data set to search: `official`, `historical`, or `all`. Default: `all`. Default value: `all` | | `par.level` | Number | No | Search level: `1` for Country and `5` for City | | `data` | Object | Yes | Search criteria for birth locality lookup | | `data.province_code` | String | No | Province code | | `data.locality` | String | No | Locality description | | `data.locality_id` | Number | No | Locality identifier | | `data.belfiore_code` | String | No | Belfiore code | | `data.minimum_date` | String | No | Start of validity date (format: YYYY-MM-DD) | | `data.maximum_date` | String | No | End of validity date (format: YYYY-MM-DD) | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/suggest/birthLocality" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"function":"official","level":5},"data":{"locality":"Viter"}}' ``` ### Response Birth locality candidate list, Belfiore 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.locality_id` | Number | No | Locality identifier | | `data.results.province_code` | String | No | Province code | | `data.results.locality` | String | No | Locality description | | `data.results.belfiore_code` | String | No | Belfiore code. In case of historical code it will be preceded by S- | | `data.results.minimum_date` | String | No | Start of validity date (format: YYYY-MM-DD) | | `data.results.maximum_date` | String | No | End of validity date (format: YYYY-MM-DD) | | `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** Birth locality candidate list, Belfiore codes, and system status. ```json { "data": { "results": [ { "locality_id": 38000000303, "province_code": "VT", "locality": "Viterbo", "belfiore_code": "M082", "minimum_date": "00010101 00:00:00", "maximum_date": "99991231 23:59:59" } ] }, "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 data** The data object is missing. ```json { "system": { "ret_code": 1, "des_ret_code": "data 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" } } ``` --- ## Validation Services Validation and normalization of addresses, names, phones, emails, tax codes, and VAT numbers. Every result has quality flags and codes. OpenAPI contract: [JSON](https://documentation.egon.com/openapi/validation-services.json) · [YAML](https://documentation.egon.com/openapi/validation-services.yaml) ### Endpoints - [Address](https://documentation.egon.com/docs/api/address.md): The Address endpoint validates and normalizes an address, returning the street, house number, postal data, Egon codes, and geographic coordinates. (`POST /api/norm`) - [Email](https://documentation.egon.com/docs/api/email.md): Validate one or more email addresses and return normalized values together with syntax and domain quality indicators. (`POST /api/norm`) - [Name](https://documentation.egon.com/docs/api/name.md): Validate personal names, sole proprietorships, company names, co-holder names, and family surnames, and return normalized and structured output. (`POST /api/norm`) - [Phone](https://documentation.egon.com/docs/api/phone.md): Validate and normalize telephone numbers provided either as individual international and national prefix components or as a single full number. (`POST /api/norm`) - [Tax Code Calculation](https://documentation.egon.com/docs/api/tax-code-calc.md): Calculate an Italian tax code (Codice Fiscale) from surname, name, gender, date of birth, and city of birth, with a quality flag for the result. (`POST /api/norm`) - [Tax Code Validation](https://documentation.egon.com/docs/api/tax-code-check.md): Check the formal validity and structure of an Italian tax code (Codice Fiscale) and get a quality flag and code that describe the result. (`POST /api/norm`) - [Tax Code Extraction](https://documentation.egon.com/docs/api/tax-code-extract.md): Extract gender, date of birth, and place of birth (city and province) from an Italian tax code (Codice Fiscale), with a quality flag. (`POST /api/norm`) - [Tax Code Verification](https://documentation.egon.com/docs/api/tax-code-match.md): Compare a tax code against a person's identifying data, including name, gender, date of birth, and birthplace. (`POST /api/norm`) - [VAT Validation](https://documentation.egon.com/docs/api/vat-check.md): Check the structure and formal validity of a VAT number (Partita IVA) and get a quality flag and code that describe the result of the check. (`POST /api/norm`) - [VAT Extraction](https://documentation.egon.com/docs/api/vat-ext.md): Validate and enrich company data from a VAT number: official business name, legal address, phone numbers, PEC email, and ATECO codes. (`POST /api/norm`) --- ## 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; `` 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" } } ``` --- ## Email Validate one or more email addresses and return normalized values together with syntax and domain quality indicators. ### 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 and collection of email addresses to validate. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context for email 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**. | | `data` | Object | Yes | Input data to validate | | `data.emails` | Array | Yes | Email addresses to validate | | `data.emails.email` | String | Yes | Email address | #### 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"},"data":{"emails":[{"email":"info@egon.com"},{"email":"info@example.com"}]}}' ``` ### Response Normalized email addresses, validation quality indicators, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.emails` | Array | No | Normalized email addresses | | `data.emails.email` | String | Yes | Email address | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.emails` | Array | No | Quality indicator results for each email | | `quality.emails.flag` | String | No | Quality flag | | `quality.emails.code` | Number | No | Quality result code | | `quality.emails.description` | String | No | Quality result 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** Email addresses verified for correct syntax and domain structure. ```json { "data": { "emails": [ { "email": "info@egon.com" }, { "email": "info@example.com" } ] }, "quality": { "emails": [ { "flag": "0", "code": 0, "description": "Ok" }, { "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" } } ``` --- ## Name Validate personal names, sole proprietorships, company names, co-holder names, and family surnames, and return normalized and structured output. ### 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 and person or company name string to validate. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context for name analysis and 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**. | | `data` | Object | Yes | Input data to validate | | `data.name` | Object | Yes | | | `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.mid_name` | String | No | Middle name | | `data.name.first_name` | String | No | First name | | `data.name.title` | String | No | Title | | `data.name.name_des` | String | No | Name description | | `data.name.birth_date` | String | No | Date of birth | | `data.name.birth_province` | String | No | Province of birth | | `data.name.birth_place` | String | No | Place of birth | #### 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"},"data":{"name":{"full_name":"Dottor Mario Rossi"}}}' ``` ### Response Structured name components, recognized gender, separated title/surname/name, and quality indicators. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.name` | Object | No | Parsed, validated, and normalized personal name details | | `data.name.type_ana` | String | No | Customer data type | | `data.name.gender` | String | No | Gender | | `data.name.full_name` | String | No | Validated full name | | `data.name.last_name` | String | No | Separate surname | | `data.name.mid_name` | String | No | Middle name | | `data.name.first_name` | String | No | Separate name | | `data.name.prename` | String | No | Name suffix (e.g. Junior/Senior) | | `data.name.title` | String | No | Academic or professional title | | `data.name.firm_type` | String | No | Official juridical specification (e.g. S.R.L., S.P.A.) | | `data.name.birth_date` | String | No | Date of birth in YYYYMMDD format | | `data.name.birth_country` | String | No | Country of birth | | `data.name.birth_province` | String | No | Province of birth | | `data.name.birth_place` | String | No | City of birth | | `data.name.name_des` | String | No | Name designator | | `data.name.status` | String | No | Status | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.name` | Object | No | Quality indicators for personal name parsing and demographic verification | | `quality.name.person` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.person.flag` | String | No | Quality flag | | `quality.name.person.code` | Number | No | Quality result code | | `quality.name.person.description` | String | No | Quality result description | | `quality.name.birth_date` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.birth_date.flag` | String | No | Quality flag | | `quality.name.birth_date.code` | Number | No | Quality result code | | `quality.name.birth_date.description` | String | No | Quality result description | | `quality.name.birth_place` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.birth_place.flag` | String | No | Quality flag | | `quality.name.birth_place.code` | Number | No | Quality result code | | `quality.name.birth_place.description` | String | No | Quality result 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** Name successfully recognized, titles separated, and structured into first name and surname. ```json { "data": { "name": { "type_ana": "1", "gender": "1", "full_name": "ROSSI,MARIO", "last_name": "ROSSI", "first_name": "MARIO", "title": "DOTTORE" } }, "quality": { "name": { "person": { "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" } } ``` --- ## Phone Validate and normalize telephone numbers provided either as individual international and national prefix components or as a single full number. ### 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 and telephone numbers to normalize and validate. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context for phone number normalization. | | `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**. | | `data` | Object | Yes | Input data to validate | | `data.phones` | Array | Yes | Collection of telephone numbers to validate | | `data.phones.pre_int` | String | No | International telephone prefix | | `data.phones.pre_nat` | String | No | National telephone prefix | | `data.phones.number` | String | Yes | Telephone 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"},"data":{"phones":[{"pre_int":"39","pre_nat":"045","number":"8200794"},{"number":"390458201847"}]}}' ``` ### Response Normalized phone numbers with country prefixes, line type codes, quality indicators, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.phones` | Array | No | Normalized telephone entries | | `data.phones.iso3` | String | No | Country code (ISO 3166-1 alpha-3) | | `data.phones.type` | String | No | Telephone-number type code | | `data.phones.pre_int` | String | No | Normalized international dialing prefix | | `data.phones.pre_nat` | String | No | Normalized national dialing prefix | | `data.phones.number` | String | No | Normalized local telephone number | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.phones` | Array | No | Quality result for each returned phone entry | | `quality.phones.flag` | String | No | Quality flag | | `quality.phones.code` | Number | No | Quality result code | | `quality.phones.description` | String | No | Quality result 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** Phone numbers validated, separated into international and national prefixes, and standardized. ```json { "data": { "phones": [ { "iso3": "ITA", "type": "00001", "pre_int": "+39", "pre_nat": "045", "number": "8200794" }, { "iso3": "ITA", "type": "00001", "pre_int": "+39", "pre_nat": "045", "number": "8201847" } ] }, "quality": { "phones": [ { "flag": "0", "code": 0, "description": "Ok" }, { "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" } } ``` --- ## Tax Code Calculation Calculate an Italian tax code (Codice Fiscale) from surname, name, gender, date of birth, and city of birth, with a quality flag for the result. ### 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, `taxfnx` function `3`, and personal identity data. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context and tax-code calculation function. | | `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.taxfnx` | String | Yes | Tax-code configuration function. `3` Calculate tax code from identity data. Default value: `3` | | `data` | Object | Yes | Input data to validate | | `data.name` | Object | Yes | Identity and demographic data used to calculate tax code | | `data.name.full_name` | String | Yes | Surname | | `data.name.first_name` | String | Yes | First name | | `data.name.gender` | String | Yes | Gender (`1` Male, `2` Female) | | `data.name.birth_date` | String | Yes | Date of birth in `YYYYMMDD` format | | `data.name.birth_place` | String | Yes | Birth city description | #### 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","taxfnx":"3"},"data":{"name":{"full_name":"Rossi","first_name":"Mario","gender":"1","birth_date":"19930219","birth_place":"Verona"}}}' ``` ### Response Calculated tax code, quality indicators for personal identity fields, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.tax_code` | Object | No | Calculated Italian tax code details | | `data.tax_code.cod_description` | String | No | Calculated Italian tax code | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.tax_code` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.tax_code.flag` | String | No | Quality flag | | `quality.tax_code.code` | Number | No | Quality result code | | `quality.tax_code.description` | String | No | Quality result description | | `quality.name` | Object | No | Quality indicators for personal name parsing and demographic verification | | `quality.name.person` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.person.flag` | String | No | Quality flag | | `quality.name.person.code` | Number | No | Quality result code | | `quality.name.person.description` | String | No | Quality result description | | `quality.name.birth_date` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.birth_date.flag` | String | No | Quality flag | | `quality.name.birth_date.code` | Number | No | Quality result code | | `quality.name.birth_date.description` | String | No | Quality result description | | `quality.name.birth_place` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.birth_place.flag` | String | No | Quality flag | | `quality.name.birth_place.code` | Number | No | Quality result code | | `quality.name.birth_place.description` | String | No | Quality result 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** Tax code calculated successfully from personal information. ```json { "data": { "tax_code": { "cod_description": "RSSMRA93B19L781K" } }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" }, "name": { "person": { "flag": "0", "code": 0, "description": "Ok" }, "birth_date": { "flag": "0", "code": 0, "description": "Ok" }, "birth_place": { "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" } } ``` --- ## Tax Code Validation Check the formal validity and structure of an Italian tax code (Codice Fiscale) and get a quality flag and code that describe the result. ### 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, `taxfnx` function `2`, and tax code to check. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context and tax-code validation function. | | `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.taxfnx` | String | Yes | Tax-code configuration function. `2` Formal check and validation. Default value: `2` | | `data` | Object | Yes | Input data to validate | | `data.tax_code` | Object | Yes | Italian tax code to validate | | `data.tax_code.cod_iso3` | String | No | Country code (ISO 3166-1 alpha-3) | | `data.tax_code.cod_type` | String | No | Type of code | | `data.tax_code.cod_description` | String | Yes | Italian tax code to check | #### 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","taxfnx":"2"},"data":{"tax_code":{"cod_iso3":"ITA","cod_type":"01110","cod_description":"RSSMRA93B19L781K"}}}' ``` ### Response Validated tax code, extraction verification quality indicator, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.tax_code` | Object | No | Validated tax code details | | `data.tax_code.cod_description` | String | No | Italian tax code | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.tax_code` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.tax_code.flag` | String | No | Quality flag | | `quality.tax_code.code` | Number | No | Quality result code | | `quality.tax_code.description` | String | No | Quality result 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** Tax code verified and found formally valid. ```json { "data": { "tax_code": { "cod_description": "RSSMRA93B19L781K" } }, "quality": { "tax_code": { "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" } } ``` --- ## Tax Code Extraction Extract gender, date of birth, and place of birth (city and province) from an Italian tax code (Codice Fiscale), with a quality flag. ### 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, `taxfnx` function `5`, and tax code to decode. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context and tax-code extraction function. | | `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.taxfnx` | String | Yes | Tax-code configuration function. `5` Extract demographic information from tax code. Default value: `5` | | `data` | Object | Yes | Input data to validate | | `data.tax_code` | Object | Yes | Italian tax code to extract demographics from | | `data.tax_code.cod_iso3` | String | No | Country code (ISO 3166-1 alpha-3) | | `data.tax_code.cod_type` | String | No | Type of code | | `data.tax_code.cod_description` | String | Yes | Italian tax code to extract info from | #### 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","taxfnx":"5"},"data":{"tax_code":{"cod_iso3":"ITA","cod_type":"01110","cod_description":"RSSMRA93B19L781K"}}}' ``` ### Response Extracted birth date, birth province, birth city, quality indicator, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.name` | Object | No | Extracted demographic and birthplace data | | `data.name.gender` | String | No | Extracted gender | | `data.name.birth_date` | String | No | Extracted date of birth in `YYYYMMDD` format | | `data.name.birth_province` | String | No | Extracted birth province code | | `data.name.birth_place` | String | No | Extracted birth city description | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.tax_code` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.tax_code.flag` | String | No | Quality flag | | `quality.tax_code.code` | Number | No | Quality result code | | `quality.tax_code.description` | String | No | Quality result 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** Birth details and province extracted successfully from the tax code. ```json { "data": { "name": { "birth_date": "19930219", "birth_province": "VR", "birth_place": "VERONA" } }, "quality": { "tax_code": { "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" } } ``` --- ## Tax Code Verification Compare a tax code against a person's identifying data, including name, gender, date of birth, and birthplace. ### 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, `taxfnx` function `1`, personal identity data, and tax code to compare. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context and tax-code match function. | | `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.taxfnx` | String | Yes | Tax-code configuration function. `1` Compare and match tax code against personal identity data. Default value: `1` | | `data` | Object | Yes | Input data to validate | | `data.name` | Object | Yes | Personal identity data to compare against tax code | | `data.name.full_name` | String | Yes | Surname | | `data.name.first_name` | String | Yes | First name | | `data.name.gender` | String | Yes | Gender (`1` Male, `2` Female) | | `data.name.birth_date` | String | Yes | Date of birth in `YYYYMMDD` format | | `data.name.birth_place` | String | Yes | Birth city description | | `data.tax_code` | Object | Yes | Italian tax code to match | | `data.tax_code.cod_iso3` | String | No | Country code (ISO 3166-1 alpha-3) | | `data.tax_code.cod_type` | String | No | Code type | | `data.tax_code.cod_description` | String | Yes | Italian tax code to match | #### 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","taxfnx":"1"},"data":{"name":{"full_name":"Rossi","first_name":"Mario","gender":"1","birth_date":"19930219","birth_place":"Verona"},"tax_code":{"cod_iso3":"ITA","cod_type":"01110","cod_description":"RSSMRA93B19L781K"}}}' ``` ### Response Normalized personal data, tax code, comparison quality results for identity, birth date, birthplace, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.name` | Object | No | Validated identity data and matching outcome | | `data.name.type_ana` | String | No | Person/customer type | | `data.name.gender` | String | No | Normalized gender | | `data.name.full_name` | String | No | Normalized full name | | `data.name.last_name` | String | No | Normalized surname | | `data.name.first_name` | String | No | Normalized first name | | `data.name.birth_date` | String | No | Date of birth in `YYYYMMDD` format | | `data.name.birth_province` | String | No | Birth province code | | `data.name.birth_place` | String | No | Normalized birthplace | | `data.tax_code` | Object | No | Matched tax code details | | `data.tax_code.cod_description` | String | No | Italian tax code result | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.tax_code` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.tax_code.flag` | String | No | Quality flag | | `quality.tax_code.code` | Number | No | Quality result code | | `quality.tax_code.description` | String | No | Quality result description | | `quality.name` | Object | No | Quality indicators for personal name parsing and demographic verification | | `quality.name.person` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.person.flag` | String | No | Quality flag | | `quality.name.person.code` | Number | No | Quality result code | | `quality.name.person.description` | String | No | Quality result description | | `quality.name.birth_date` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.birth_date.flag` | String | No | Quality flag | | `quality.name.birth_date.code` | Number | No | Quality result code | | `quality.name.birth_date.description` | String | No | Quality result description | | `quality.name.birth_place` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.name.birth_place.flag` | String | No | Quality flag | | `quality.name.birth_place.code` | Number | No | Quality result code | | `quality.name.birth_place.description` | String | No | Quality result 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** Tax code matches personal information completely. ```json { "data": { "name": { "type_ana": "1", "gender": "1", "full_name": "ROSSI,MARIO", "last_name": "ROSSI", "first_name": "MARIO", "birth_date": "19930219", "birth_province": "VR", "birth_place": "VERONA" }, "tax_code": { "cod_description": "RSSMRA93B19L781K" } }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" }, "name": { "person": { "flag": "0", "code": 0, "description": "Ok" }, "birth_date": { "flag": "0", "code": 0, "description": "Ok" }, "birth_place": { "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" } } ``` --- ## VAT Validation Check the structure and formal validity of a VAT number (Partita IVA) and get a quality flag and code that describe the result of the check. ### 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 and VAT number to validate. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context for VAT number formal 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**. | | `data` | Object | Yes | Input data to validate | | `data.vat_number` | Object | Yes | VAT number to formally validate | | `data.vat_number.cod_iso3` | String | No | Country code (ISO 3166-1 alpha-3) | | `data.vat_number.cod_type` | String | No | Type of code | | `data.vat_number.cod_description` | String | Yes | VAT number to check | #### 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"},"data":{"vat_number":{"cod_iso3":"ITA","cod_type":"01111","cod_description":"10851310960"}}}' ``` ### Response Validated VAT number, verification quality indicator, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.vat_number` | Object | No | Formal validation outcome for VAT number | | `data.vat_number.cod_description` | String | No | Validated VAT number | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.vat_number` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.vat_number.flag` | String | No | Quality flag | | `quality.vat_number.code` | Number | No | Quality result code | | `quality.vat_number.description` | String | No | Quality result 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** VAT number validated and found formally correct. ```json { "data": { "vat_number": { "cod_description": "10851310960" } }, "quality": { "vat_number": { "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" } } ``` --- ## VAT Extraction Validate and enrich company data from a VAT number: official business name, legal address, phone numbers, PEC email, and ATECO codes. ### 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, `vatfnx` function `E`, and VAT number to enrich. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | Country context and extended VAT function. | | `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.vatfnx` | String | Yes | VAT-number configuration function. `E` Extended company registry details lookup. Default value: `E` | | `data` | Object | Yes | Input data to validate | | `data.vat_number` | Object | Yes | VAT number to query extended company registry for | | `data.vat_number.cod_description` | String | Yes | VAT number to enrich | #### 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","vatfnx":"E"},"data":{"vat_number":{"cod_description":"01032450072"}}}' ``` ### Response Enriched company profile including business name, tax code, address, phones, emails, activity codes, and quality indicator. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Normalized and enriched validation output data | | `data.name` | Object | No | Company business name and legal form | | `data.name.firm_name` | String | No | Company name | | `data.name.title` | String | No | Company juridical form | | `data.name.status` | String | No | Company operational status | | `data.tax_code` | Object | No | Company fiscal code details | | `data.tax_code.cod_description` | String | No | Tax code description | | `data.vat_number` | Object | No | Extended VAT registration details | | `data.vat_number.cod_description` | String | No | VAT number | | `data.address` | Object | No | Company registered office address details | | `data.address.standard` | Object | No | Standardized company registered address details | | `data.address.standard.country` | String | No | Country | | `data.address.standard.province` | String | No | Province description | | `data.address.standard.province_code` | String | No | Province abbreviation | | `data.address.standard.city` | String | No | City name | | `data.address.standard.zipcode` | String | No | Postal code | | `data.address.standard.street_type` | String | No | Street type | | `data.address.standard.street_name` | String | No | Street name | | `data.address.standard.full_address` | String | No | Full normalized address | | `data.address.standard.hn` | String | No | House number | | `data.phones` | Object | No | Associated company phone numbers | | `data.phones.type` | String | No | Phone type | | `data.phones.number` | String | No | Phone number | | `data.emails` | Object | No | Associated company email addresses | | `data.emails.type` | String | No | Email type | | `data.emails.email` | String | No | Certified email address (PEC) | | `data.codes` | Object | No | Economic activity (Ateco) and registry codes | | `data.codes.type` | String | No | Code type | | `data.codes.cod_description` | String | No | ATECO economic activity code | | `quality` | Object | No | Validation quality indicators and score flags | | `quality.vat_number` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) | | `quality.vat_number.flag` | String | No | Quality flag | | `quality.vat_number.code` | Number | No | Quality result code | | `quality.vat_number.description` | String | No | Quality result 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** Company information enriched from VAT number. ```json { "data": { "name": { "firm_name": "CVA ENERGIE SRL", "title": "Societa' A Responsabilita' Limitata", "status": "Attiva" }, "tax_code": { "cod_description": "01032450072" }, "vat_number": { "cod_description": "01032450072" }, "address": { "standard": { "country": "Italia", "province": "Valle D'Aosta/Valle D'Aoste", "province_code": "AO", "city": "CHATILLON", "zipcode": "11024", "street_type": "VIA", "street_name": "STAZIONE", "full_address": "VIA STAZIONE 31, CHATILLON 11024 AO Valle D'Aosta/Valle D'Aoste Italia", "hn": "31" } }, "phones": [ { "type": "00001", "number": "0166822925" }, { "type": "00003", "number": "0166821032" } ], "emails": [ { "type": "01601", "email": "azienda@pec.example.com" }, { "type": "01115", "email": "info@example.com" } ], "codes": [ { "type": "01600", "cod_description": "3514" }, { "type": "01116", "cod_description": "cvatrading.it" }, { "type": "CBILL", "cod_description": "CVA ENERGIE S.R.L.#CPVVN#01032450072#002" }, { "type": "CBILL", "cod_description": "CVA ENERGIE SRL BUSIN. E SMALL BUS. M.L.#93Z76#01032450072#001" }, { "type": "CBILL", "cod_description": "CVA ENERGIE SRL CLIENTI MERCATO MAGGIOR TUTELA#7G770#01032450072#001" }, { "type": "CBILL", "cod_description": "CVA ENERGIE SRL CLIENTI RETAIL MERCATO LIBERO#AZKH5#01032450072#001" } ] }, "quality": { "vat_number": { "flag": "1", "code": 911, "description": "CODICE TROVATO: ARRICCHITI DATI DA LIVELLO 2" } }, "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" } } ``` --- ## Single Line Service Recognition and normalization of a complete address written as a single free-text string. Returns a list of normalized candidates to choose from. OpenAPI contract: [JSON](https://documentation.egon.com/openapi/single-line-service.json) · [YAML](https://documentation.egon.com/openapi/single-line-service.yaml) ### Endpoints - [Full Address](https://documentation.egon.com/docs/api/full-address.md): The Full Address endpoint parses a complete address written as a single free-text string and returns a list of normalized candidate addresses. (`POST /api/single-line/full-address`) --- ## 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**. ### 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" } } ``` --- ## Reverse Geocoding Conversion of geographic coordinates into normalized addresses. Returns the nearest house numbers with street, postal code, and distance. OpenAPI contract: [JSON](https://documentation.egon.com/openapi/reverse-geocoding.json) · [YAML](https://documentation.egon.com/openapi/reverse-geocoding.yaml) ### Endpoints - [Address from Coordinates](https://documentation.egon.com/docs/api/reverse.md): The Reverse geocoding service retrieves address candidates from geographic coordinates, with street, house number, postal code, and distance. (`POST /api/revGeo`) --- ## Address from Coordinates The Reverse geocoding service retrieves **address candidates** from geographic coordinates, with street, house number, postal code, and distance. ### Endpoint `POST https://{host}:{port}/Egon/api/revGeo` 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 Geographic coordinates (latitude, longitude), radius, and search options. | Field | Type | Required | Description | | --- | --- | --- | --- | | `par` | Object | Yes | | | `par.iso3` | String | Yes | Country code (ISO 3166-1 alpha-3) | | `par.type` | String | No | Type of reverse: `P` punctual or `V` vector. Default value: `P` | | `par.radius` | Number | No | Radius from the input coordinates, in meters. Default value: `100` | | `par.increase_radius` | Number | No | Increased search radius. Default value: `1` | | `par.search_attempts` | Number | No | Number of search attempts. Default value: `1` | | `par.max_candidates` | Number | No | Maximum number of candidates to extract. Default value: `10` | | `data` | Object | Yes | | | `data.latitude` | Number | Yes | Latitude | | `data.longitude` | Number | Yes | Longitude | #### Example request ```bash curl -X POST "https://{host}:{port}/Egon/api/revGeo" \ -H "token: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"par":{"iso3":"ITA"},"data":{"longitude":10.97382316,"latitude":45.406161}}' ``` ### Response Nearest address candidates, distance, administrative hierarchy, and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | | | `data.results` | Array | No | Reverse-geocoding results | | `data.results.hn_id` | Number | No | ID of the number | | `data.results.province_code` | String | No | Province code | | `data.results.city` | String | No | City description | | `data.results.locality` | String | No | District description | | `data.results.street` | String | No | Street name | | `data.results.zipcode` | String | No | Postal code | | `data.results.hn` | String | No | House number | | `data.results.exponent` | String | No | Exponent | | `data.results.longitude` | String | No | Longitude | | `data.results.latitude` | String | No | Latitude | | `data.results.distance` | Number | No | Distance (in meters) | | `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** Nearest address candidates, distance, administrative hierarchy, and system status. ```json { "data": { "results": [ { "hn_id": 380100008326045, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO PACINOTTI", "zipcode": "37135", "hn": "4", "exponent": "B", "longitude": "10.973796", "latitude": "45.406168", "distance": 3 }, { "hn_id": 380600052104491, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO PACINOTTI", "zipcode": "37135", "hn": "4", "exponent": "C", "longitude": "10.97373", "latitude": "45.4061", "distance": 12 }, { "hn_id": 380100008311753, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO MEUCCI", "zipcode": "37135", "hn": "1", "longitude": "10.973873", "latitude": "45.406044", "distance": 14 }, { "hn_id": 380100008326075, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO PACINOTTI", "zipcode": "37135", "hn": "5", "longitude": "10.97367", "latitude": "45.40611", "distance": 18 }, { "hn_id": 380100008326087, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO PACINOTTI", "zipcode": "37135", "hn": "7", "exponent": "A", "longitude": "10.97367", "latitude": "45.4061", "distance": 18 }, { "hn_id": 380100008311777, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO MEUCCI", "zipcode": "37135", "hn": "2", "exponent": "A", "longitude": "10.97379", "latitude": "45.40588", "distance": 31 }, { "hn_id": 380100008326051, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO PACINOTTI", "zipcode": "37135", "hn": "4", "longitude": "10.9735", "latitude": "45.40615", "distance": 36 }, { "hn_id": 380100008311789, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO MEUCCI", "zipcode": "37135", "hn": "2", "longitude": "10.97373", "latitude": "45.40574", "distance": 48 }, { "hn_id": 380100008326039, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO PACINOTTI", "zipcode": "37135", "hn": "4", "exponent": "A", "longitude": "10.97308", "latitude": "45.40625", "distance": 83 }, { "hn_id": 380100008311813, "province_code": "VR", "city": "VERONA", "street": "VIA ANTONIO MEUCCI", "zipcode": "37135", "hn": "5", "longitude": "10.97354", "latitude": "45.40536", "distance": 94 } ] }, "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 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" } } ``` --- ## Map Broker Services Route calculation and distance matrix services. The Routing endpoint calculates routes for a generic vehicle or for pedestrians. OpenAPI contract: [JSON](https://documentation.egon.com/openapi/map-broker-services.json) · [YAML](https://documentation.egon.com/openapi/map-broker-services.yaml) ### Endpoints - [Routing](https://documentation.egon.com/docs/api/routing.md): Calculate a route between an origin and a destination for a generic vehicle or a pedestrian, based on the HERE Routing API v8. (`POST /api/routes`) --- ## Routing Calculate a route between an origin and a destination for a generic vehicle or a pedestrian, based on the HERE Routing API v8. To see the full list of parameters or their details, visit the [HERE Routing API documentation](https://docs.here.com/routing/reference/routing-api-v8-calculateroutespost). ### Endpoint `POST https://{host}:{port}/EgonMbk/api/routes` 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 | Field | Type | Required | Description | | --- | --- | --- | --- | | `transportMode` | String | Yes | Mode of transport: `car`, `truck`, `pedestrian`, `bicycle`, `scooter`, `taxi`, `bus`, `privateBus`, or `networkRestrictedTruck`. Default value: `car` | | `origin` | String | Yes | Origin waypoint (WGS84). Format: `{lat},{lng}`. | | `destination` | String | Yes | Destination waypoint (WGS84). Format: `{lat},{lng}`. | | `via` | String | No | Via waypoint(s). Multiple values are allowed and are traversed sequentially in the specified order. | | `routingMode` | String | No | Route optimization: `fast` (default) or `short`. Default value: `fast` | | `return` | String | No | Attributes to include in the response, including `polyline`, `actions`, `instructions`, `summary`, `travelSummary`, `turnByTurnActions`, `elevation`, `routeHandle`, `incidents`, and `tolls`. | | `spans` | String | No | Map content attributes to include per span. Requires `return=polyline`. | | `units` | String | No | Units of measurement: `metric` (default) or `imperial`. Default value: `metric` | | `lang` | String | No | Preferred response language in BCP 47 format, for example `it,en-US`. | #### Example request ```bash curl -X POST "https://{host}:{port}/EgonMbk/api/routes?transportMode=car&origin=44.9741733,7.7232365&destination=43.87644,11.11885&routingMode=fast&units=metric" \ -H "token: YOUR_API_KEY" ``` ### Response Calculated routes and system status. | Field | Type | Required | Description | | --- | --- | --- | --- | | `data` | Object | No | Calculated route data. | | `data.routes` | Array | No | Route(s) calculated. | | `data.routes.id` | String | No | Unique route id. | | `data.routes.sections` | Array | No | Sections composing the route. | | `data.routes.sections.id` | String | No | Section id. | | `data.routes.sections.type` | String | No | Section type: `vehicle`, `pedestrian`, or `transit`. | | `data.routes.sections.departure` | Object | No | | | `data.routes.sections.departure.place` | Object | No | | | `data.routes.sections.departure.place.type` | String | No | Type of place. | | `data.routes.sections.departure.place.location` | Object | No | | | `data.routes.sections.departure.place.location.lat` | Number | No | Latitude (WGS84). | | `data.routes.sections.departure.place.location.lng` | Number | No | Longitude (WGS84). | | `data.routes.sections.departure.place.originalLocation` | Object | No | | | `data.routes.sections.departure.place.originalLocation.lat` | Number | No | Latitude (WGS84). | | `data.routes.sections.departure.place.originalLocation.lng` | Number | No | Longitude (WGS84). | | `data.routes.sections.arrival` | Object | No | | | `data.routes.sections.arrival.place` | Object | No | | | `data.routes.sections.arrival.place.type` | String | No | Type of place. | | `data.routes.sections.arrival.place.location` | Object | No | | | `data.routes.sections.arrival.place.location.lat` | Number | No | Latitude (WGS84). | | `data.routes.sections.arrival.place.location.lng` | Number | No | Longitude (WGS84). | | `data.routes.sections.arrival.place.originalLocation` | Object | No | | | `data.routes.sections.arrival.place.originalLocation.lat` | Number | No | Latitude (WGS84). | | `data.routes.sections.arrival.place.originalLocation.lng` | Number | No | Longitude (WGS84). | | `data.routes.sections.summary` | Object | No | | | `data.routes.sections.summary.duration` | Number | No | Duration in seconds. | | `data.routes.sections.summary.length` | Number | No | Length in meters. | | `data.routes.sections.summary.baseDuration` | Number | No | Duration ignoring traffic conditions. | | `data.routes.sections.transport` | Object | No | | | `data.routes.sections.transport.mode` | String | No | Mode of transport used. | | `data.routes.sections.polyline` | String | No | Route geometry in Flexible Polyline encoding. | | `data.routes.sections.actions` | Array | No | Actions required to complete the section. | | `data.routes.sections.spans` | Array | No | Map content attributes for each span. | | `data.routes.routeLabels` | Array of String | No | Most important names and route numbers. | | `data.routes.routeHandle` | String | No | Encoded route handle for later route decoding. | | `data.notices` | Array | No | Issues related to the route calculation. | | `system` | Object | No | System error status. | | `system.ret_code` | Number | No | Code: `0` means no blocking error; a value different from `0` is a blocking error code. | | `system.des_ret_code` | String | No | Description of the return status. | #### Example responses **HTTP 200: Valid response** Route successfully calculated between origin and destination. ```json { "data": { "routes": [ { "id": "8806be89-f32f-4dab-a794-5717c6e2720d", "sections": [ { "id": "9f11b95c-d189-4d58-8701-f70a245ca6da", "type": "vehicle", "departure": { "place": { "type": "place", "location": { "lat": 44.9741733, "lng": 7.7232365 }, "originalLocation": { "lat": 44.9741733, "lng": 7.7232365 } } }, "arrival": { "place": { "type": "place", "location": { "lat": 43.87644, "lng": 11.11885 }, "originalLocation": { "lat": 43.87644, "lng": 11.11885 } } }, "transport": { "mode": "car" } } ] } ] }, "system": { "retCode": 0, "desRetCode": "Ok" } } ``` **HTTP 200: Missing parameters** Parameters are missing. ```json { "system": { "ret_code": 1, "des_ret_code": "Invalid request" } } ``` **HTTP 200: Incomplete parameters** Parameters are incomplete. ```json { "system": { "ret_code": 1, "des_ret_code": "Malformed request" } } ``` **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" } } ``` --- ## Quality Indicators Quality indicators describe how Egon validated, changed, rejected, or approximated an input value during postal standardization and data validation services. ### How to Read an Indicator Each quality result in an API response contains three key elements: | Field | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------ | | `flag` | `String` | High-level validation status indicating whether data was unchanged, corrected, or rejected | | `code` | `Number` | Granular error or quality rule code specifying the exact operation performed | | `description` | `String` | Human-readable explanation of the validation outcome | ### Flag Values The high-level `flag` summarizes the overall validation outcome: | Flag | Status | Meaning | | --------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 0 · OK | **Validated without changes** | The input value perfectly matched reference authority databases and required no alterations. | | 1 · Changed | **Validated with changes** | The input value was recognized and corrected, completed, or standardized according to official postal rules. | | 2/3 · Not valid | **Not validated** | The value could not be validated due to ambiguity, syntax errors, missing mandatory elements, or no matching records found. | ### Indicator Catalogs - [Address Indicators](https://documentation.egon.com/docs/quality-indicators/address.md): Detailed quality codes for locality, street name, postal code, and house-number validation. (201 codes) - [Birth Indicators](https://documentation.egon.com/docs/quality-indicators/birth.md): Quality indicators returned for birth-date coherence and birthplace validation. (8 codes) - [Email Indicators](https://documentation.egon.com/docs/quality-indicators/email.md): Syntax validation, domain verification, certified PEC identification, and disposable email detection. (32 codes) - [Geocoding Indicators](https://documentation.egon.com/docs/quality-indicators/geocoding.md): Coordinate sources (TomTom, HERE, Egon, cadastre) and spatial precision approximation levels. (88 codes) - [Person & Name Indicators](https://documentation.egon.com/docs/quality-indicators/person.md): Name and surname parsing, academic title detection, corporate legal forms, and gender consistency. (46 codes) - [Phone Indicators](https://documentation.egon.com/docs/quality-indicators/phone.md): Telephone number standardization, international prefix addition, and geographical area code checks. (25 codes) - [Tax Code Indicators](https://documentation.egon.com/docs/quality-indicators/tax-code.md): Italian fiscal code calculation, checksum verification, omocody resolution, and identity checks. (59 codes) - [VAT Indicators](https://documentation.egon.com/docs/quality-indicators/vat.md): VAT number syntax validation, European VIES cross-checks, and corporate registry verification. (59 codes) ### Also in Reference Complementary reference guide and data dictionary: - [Domains & Dictionaries](https://documentation.egon.com/docs/domains.md): Standardized domain codes used in request and response fields (administrative codes, person types, phone lines). --- ## Address Quality Indicators Quality indicators returned for locality, street, postal code, and house-number validation in Egon Address and Single Line services. ### Locality Indicators Locality-level verification codes indicating administrative boundary matches, postal code corrections, and phonetic normalization. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 701 | Locality candidate found | | 1 (Changed) | 702 | Locality candidate found with different level | | 1 (Changed) | 703 | Postcode not correct | | 1 (Changed) | 704 | Different postcode for mono-postcode locality | | 1 (Changed) | 705 | Different postcode for multi-postcode locality | | 1 (Changed) | 706 | Different postcode for mono-postcode street | | 1 (Changed) | 707 | Different postcode for multi-postcode street | | 1 (Changed) | 708 | District 1 not validated | | 1 (Changed) | 709 | Different words | | 1 (Changed) | 710 | Locality with more words | | 1 (Changed) | 711 | Locality with two less words | | 1 (Changed) | 712 | Too many less words | | 1 (Changed) | 713 | Postcode found | | 1 (Changed) | 714 | Locality found | | 1 (Changed) | 715 | Postcode different from Department postcode | | 1 (Changed) | 716 | Special postcode | | 1 (Changed) | 717 | Special postcode | | 1 (Changed) | 724 | Postcode different from postal town postcode | | 1 (Changed) | 727 | Locality out of Country | | 1 (Changed) | 728 | Locality out of range | | 1 (Changed) | 729 | Locality found in the state of the input locality | | 1 (Changed) | 730 | Locality found at an equivalent level | | 1 (Changed) | 731 | Locality found with inverted levels | | 1 (Changed) | 732 | Locality found with inverted sub-levels | | 1 (Changed) | 734 | Locality extracted from Postcode | | 1 (Changed) | 751 | Locality found in the metropolitan area of the input city | | 1 (Changed) | 752 | Locality extracted from postal town | | 1 (Changed) | 780 | Locality found with synonym | | 1 (Changed) | 782 | Locality found with user synonym | | 1 (Changed) | 783 | Locality found with automatic synonym | | 1 (Changed) | 784 | Locality found with historic synonym | | 1 (Changed) | 785 | Locality found with user synonym type 5 | | 1 (Changed) | 786 | Locality found with user synonym type 6 | | 1 (Changed) | 787 | Locality found with user synonym type 7 | | 1 (Changed) | 788 | Locality found with user synonym type 8 | | 1 (Changed) | 789 | Locality found with user synonym type 9 | | 1 (Changed) | 790 | Locality validated after post-treatment | | 1 (Changed) | 791 | Locality validated with consonants candidates | | 1 (Changed) | 792 | Locality validated with vowel candidates | | 1 (Changed) | 793 | Locality validated with forced candidate | | 1 (Changed) | 794 | Locality validated with different Province | | 1 (Changed) | 798 | Country extracted from locality | | 1 (Changed) | 799 | Changed Country | | 2/3 (Not valid) | 201 | No data - locality | | 2/3 (Not valid) | 202 | Locality not found | | 2/3 (Not valid) | 203 | Ambiguous locality | | 2/3 (Not valid) | 204 | Invalid data | | 2/3 (Not valid) | 205 | Locality with words out of sequence | | 2/3 (Not valid) | 206 | Locality candidate out of sequence | | 2/3 (Not valid) | 207 | Locality with more words | | 2/3 (Not valid) | 208 | Locality with invalid elements | | 2/3 (Not valid) | 209 | Locality with first word not found | | 2/3 (Not valid) | 210 | Locality out of sequence | | 2/3 (Not valid) | 211 | Too many candidates for locality | | 2/3 (Not valid) | 212 | Locality not found, no candidates | | 2/3 (Not valid) | 213 | Candidate with one missing word | | 2/3 (Not valid) | 214 | Too many candidates for sub-locality | | 2/3 (Not valid) | 215 | Too many candidates | | 2/3 (Not valid) | 216 | Locality out of Country | | 2/3 (Not valid) | 217 | Ambiguous Country | | 2/3 (Not valid) | 218 | Ambiguous data out of Country | | 2/3 (Not valid) | 219 | Candidate with too many missing words | | 2/3 (Not valid) | 220 | Poor information for matchcode construction | | 2/3 (Not valid) | 221 | Postal town not found | | 2/3 (Not valid) | 222 | Postal town not found | | 2/3 (Not valid) | 223 | Postal town inconsistent data | | 2/3 (Not valid) | 224 | Postcode incongruous with postal town | | 2/3 (Not valid) | 225 | Locality and postcode ambiguous | | 2/3 (Not valid) | 226 | Foreign Country not found | | 2/3 (Not valid) | 227 | Foreign locality not found | | 2/3 (Not valid) | 228 | Special postcode not correct | | 2/3 (Not valid) | 229 | Territorial level not belonging to Country | | 2/3 (Not valid) | 238 | Locality candidate extracted by phonetic | | 2/3 (Not valid) | 242 | Mandatory element | | 2/3 (Not valid) | 243 | Relative weight too low | | 2/3 (Not valid) | 244 | Inconsistent territorial level | ### Street Indicators Street-level verification codes describing road name corrections, street type expansions, and postal code resolution. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 801 | Street candidate found | | 1 (Changed) | 802 | House number not present | | 1 (Changed) | 803 | Postcode corrected | | 1 (Changed) | 804 | Additional information not correct | | 1 (Changed) | 805 | CO inside address | | 1 (Changed) | 806 | CO at the beginning of address | | 1 (Changed) | 807 | First word not correct | | 1 (Changed) | 808 | Address with two less words | | 1 (Changed) | 809 | Address with different words | | 1 (Changed) | 810 | Address with more words | | 1 (Changed) | 811 | Wrong Street-type | | 1 (Changed) | 812 | Street with too many less words | | 1 (Changed) | 813 | Different postcode | | 1 (Changed) | 814 | Different postcode | | 1 (Changed) | 815 | Valid generic postcode | | 1 (Changed) | 816 | Valid generic postcode attributed | | 1 (Changed) | 817 | Address with only one word | | 1 (Changed) | 818 | Only numbers in the address | | 1 (Changed) | 819 | Address found with number analysis | | 1 (Changed) | 820 | Numbers in the street name | | 1 (Changed) | 821 | P.O. box found | | 1 (Changed) | 822 | Locality in extra-information | | 1 (Changed) | 823 | Locality in extra-information | | 1 (Changed) | 824 | Address validated from the CO section | | 1 (Changed) | 825 | Address validated from the CO section | | 1 (Changed) | 826 | Address not validated from the CO section | | 1 (Changed) | 827 | Address out of Country | | 1 (Changed) | 828 | House number found | | 1 (Changed) | 830 | P.O. box found | | 1 (Changed) | 831 | Different postcode for P.O. box | | 1 (Changed) | 832 | Postcode not valid for P.O. box | | 1 (Changed) | 833 | Street with one less word | | 1 (Changed) | 834 | Street out of sequence | | 1 (Changed) | 835 | Street with one more word | | 1 (Changed) | 836 | Street with one more number | | 1 (Changed) | 837 | Street with one more word | | 1 (Changed) | 838 | Street validated with macro street-type | | 1 (Changed) | 840 | Street not congruous with district | | 1 (Changed) | 841 | District validated from street name | | 1 (Changed) | 842 | Double street | | 1 (Changed) | 843 | Street with corner | | 1 (Changed) | 845 | Postcode valid for the street | | 1 (Changed) | 846 | Valid postcode for locality | | 1 (Changed) | 851 | Valid postcode unique postcode street | | 1 (Changed) | 852 | Valid postcode multi postcode street | | 1 (Changed) | 853 | Postcode extracted unique postcode | | 1 (Changed) | 855 | Postcode belonging to street | | 1 (Changed) | 879 | Postcode not present for multi postcode street | | 1 (Changed) | 880 | Address validated with synonym | | 1 (Changed) | 881 | Address not verified for Country without street database | | 1 (Changed) | 882 | Address validated with user synonym | | 1 (Changed) | 883 | Address validated with automatic synonym | | 1 (Changed) | 884 | Address validated with historic synonym | | 1 (Changed) | 885 | Address validated with user synonym type 5 | | 1 (Changed) | 886 | Address validated with user synonym type 6 | | 1 (Changed) | 887 | Address validated with user synonym type 7 | | 1 (Changed) | 888 | Address validated with user synonym type 8 | | 1 (Changed) | 889 | Address validated with user synonym type 9 | | 1 (Changed) | 890 | Address validated after post-treatment | | 1 (Changed) | 891 | Address validated with word candidates | | 1 (Changed) | 892 | Address validated with consonants candidates | | 1 (Changed) | 893 | Address validated with vowel candidates | | 1 (Changed) | 894 | Address validated with forced candidate | | 1 (Changed) | 895 | Locality extracted from address | | 2/3 (Not valid) | 301 | No data - street | | 2/3 (Not valid) | 302 | Street not found | | 2/3 (Not valid) | 303 | Ambiguous street | | 2/3 (Not valid) | 304 | Invalid data | | 2/3 (Not valid) | 305 | Postcode not attributable for the house number | | 2/3 (Not valid) | 306 | Street with words out of sequence | | 2/3 (Not valid) | 307 | Street with more words | | 2/3 (Not valid) | 308 | Street with invalid elements | | 2/3 (Not valid) | 309 | Street with first word not found | | 2/3 (Not valid) | 310 | Street not extracted | | 2/3 (Not valid) | 311 | Too many candidates for street | | 2/3 (Not valid) | 312 | Street candidates not found | | 2/3 (Not valid) | 313 | House number not valid | | 2/3 (Not valid) | 314 | Too many postcode ranges | | 2/3 (Not valid) | 315 | Too many house numbers | | 2/3 (Not valid) | 316 | Extraurban street not valid | | 2/3 (Not valid) | 317 | Extraurban street not valid | | 2/3 (Not valid) | 318 | Extraurban street not valid | | 2/3 (Not valid) | 319 | Extraurban street not valid | | 2/3 (Not valid) | 320 | Street with too many commas | | 2/3 (Not valid) | 321 | Street with comma and separated house number | | 2/3 (Not valid) | 322 | Two street-type found | | 2/3 (Not valid) | 323 | Address mask not found | | 2/3 (Not valid) | 324 | House number not found | | 2/3 (Not valid) | 325 | Ambiguous street | | 2/3 (Not valid) | 326 | Ambiguous street and postcode | | 2/3 (Not valid) | 327 | House number not found for multi-postcode street | | 2/3 (Not valid) | 328 | Street not recognizable | | 2/3 (Not valid) | 329 | Postcode not valid | | 2/3 (Not valid) | 330 | Street-type not valid | | 2/3 (Not valid) | 331 | Candidate with too many less words | | 2/3 (Not valid) | 332 | Street not verified caused by locality error | | 2/3 (Not valid) | 333 | Double CO | | 2/3 (Not valid) | 334 | Mask error | | 2/3 (Not valid) | 335 | Candidates not valid | | 2/3 (Not valid) | 336 | Address equal to locality | | 2/3 (Not valid) | 337 | Address not valid | | 2/3 (Not valid) | 338 | Candidates not valid | | 2/3 (Not valid) | 339 | Foreign address not found | | 2/3 (Not valid) | 340 | Too many particular words in the address | | 2/3 (Not valid) | 341 | Second street wrong | | 2/3 (Not valid) | 342 | Mandatory element | | 2/3 (Not valid) | 343 | Relative weight too low | | 2/3 (Not valid) | 344 | Exponent not found in the range | | 2/3 (Not valid) | 345 | Range not found for the street | | 2/3 (Not valid) | 391 | Wrong street direction | | 2/3 (Not valid) | 399 | Street forced by user | | 2/3 (Not valid) | 997 | Street not processed because of a country error | | 2/3 (Not valid) | 999 | Logic error | ### House-Number Indicators House-number verification codes indicating exact postal point certification, numeric-only validation, and range checks. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | Certified House number | | 1 (Changed) | 502 | House Number not certified | | 1 (Changed) | 503 | Certified house number numeric part only | | 1 (Changed) | 504 | House number code not found | | 1 (Changed) | 505 | House number code reassigned | | 1 (Changed) | 506 | House number not certified numeric part only | | 1 (Changed) | 590 | Certification not active | | 2/3 (Not valid) | 501 | House number not found | | 2/3 (Not valid) | 598 | House number not present in input | | 2/3 (Not valid) | 599 | House number not verified caused by street error | --- ## Birth Quality Indicators Reference codes returned for birth-date and birthplace validation in Egon Validation services. ### Quality Codes Quality codes indicating the outcome of date of birth validity, province sigle matching, and cadastral code alignment. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 910 | Ambiguous date of birth | | 1 (Changed) | 911 | Province code not valid | | 1 (Changed) | 912 | Incongruent date of birth | | 1 (Changed) | 913 | Incongruent Cadastral code | | 1 (Changed) | 914 | Date of birth out of range | | 1 (Changed) | 915 | Different place of birth | | 1 (Changed) | 916 | Foreign place of birth | --- ## Email Quality Indicators Reference codes returned in `quality.emails` by the Egon Email validation service. ### Quality Codes Detailed indicators describing email format compliance, domain verification, certified PEC statuses, and syntax modifications. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 463 | Double points | | 1 (Changed) | 464 | IP Formatted email | | 1 (Changed) | 465 | Points found | | 1 (Changed) | 466 | Valid Domain | | 1 (Changed) | 467 | Email with generic National first-level domain | | 1 (Changed) | 468 | Email with national first-level domain | | 1 (Changed) | 469 | Email with official domain | | 1 (Changed) | 980 | First-level domain not certified | | 1 (Changed) | 981 | Forced | | 1 (Changed) | 982 | Substitution | | 1 (Changed) | 983 | Email modified | | 1 (Changed) | 984 | Domain modified | | 1 (Changed) | 985 | Fake email | | 1 (Changed) | 986 | Email starting with special characters | | 1 (Changed) | 987 | URL in email | | 1 (Changed) | 988 | Too many emails | | 1 (Changed) | 989 | Additional information found | | 1 (Changed) | 991 | Certified domain | | 2/3 (Not valid) | 401 | Email not present | | 2/3 (Not valid) | 402 | Wrong email format | | 2/3 (Not valid) | 428 | Invalid characters | | 2/3 (Not valid) | 443 | Wrong domain | | 2/3 (Not valid) | 454 | Wrong top-level domain | | 2/3 (Not valid) | 455 | Wrong domain | | 2/3 (Not valid) | 456 | Not present | | 2/3 (Not valid) | 457 | Second-level domain not present | | 2/3 (Not valid) | 458 | Domain not certified | | 2/3 (Not valid) | 460 | Format not valid | | 2/3 (Not valid) | 461 | Email format not recognized | | 2/3 (Not valid) | 462 | Unknown domain | | 2/3 (Not valid) | 470 | Not valid domain | --- ## Geocoding Quality Indicators Reference values for spatial sources, provider datasets, and approximation levels of returned geographical coordinates. ### Coordinate Source Types The prefix indicates the territorial geometry type of returned coordinates. | Prefix | Description | | --- | --- | | A | Point on the street graph | | M | Centroid of a sub-locality polygon, census area, or specific postcode | | B | Centroid of a locality polygon | ### Provider Source Codes Granular codes identifying the provider and method used to obtain the coordinates (e.g., TomTom, HERE, Egon proprietary dataset, Cadastre, Google, OpenStreetMap). | Code | Description | | --- | --- | | A11 | TomTom Address Point | | A12 | TomTom Interpolated | | A13 | TomTom Interpolated TBD | | A14 | TomTom Low Quality | | A15 | TomTom POI | | A16 | TomTom Crossroad | | A19 | TomTom Street level | | A21 | HERE Point addressing | | A22 | HERE Interpolated GN4 | | A23 | HERE Interpolated | | A24 | HERE Low Quality | | A25 | HERE POI | | A26 | HERE crossroad | | A29 | HERE street level | | A31 | Local Authorities/Government Detected | | A33 | Local Authorities/Government Interpolated | | A34 | Local Authorities/Government Low Quality | | A35 | Local Authorities/Government POI | | A36 | Local Authorities/Government Crossroad | | A39 | Local Authorities/Government Street level | | A41 | Egon Detected | | A43 | Egon Interpolated | | A44 | Egon Low Quality | | A45 | Egon POI | | A46 | Egon Crossroad | | A49 | Egon Street level | | A51 | Custom Detected | | A53 | Custom Interpolated | | A54 | Custom Low Quality | | A55 | Custom POI | | A56 | Custom Incroci | | A59 | Custom Livello stradale | | A61 | Google Detected | | A63 | Google Interpolated | | A64 | Google Low Quality | | A65 | Google POI | | A66 | Google Crossroad | | A69 | Google Street level | | A71 | OpenStreetMap Detected | | A73 | OpenStreetMap Interpolated | | A74 | OpenStreetMap Low Quality | | A75 | OpenStreetMap POI | | A76 | OpenStreetMap Crossroad | | A79 | OpenStreetMap Street level | | A81 | Statistical source Detected | | A83 | Statistical source Interpolated | | A84 | Statistical source Low Quality | | A85 | Statistical source POI | | A86 | Statistical source Crossroad | | A89 | Statistical source Street level | | A91 | Source 9 Detected | | A93 | Source 9 Interpolated | | A94 | Source 9 Low Quality | | A95 | Source 9 POI | | A96 | Source 9 Crossroad | | A99 | Source 9 Street level | | M10 | Census centroid | | M20 | Urban zone centroid | | M30 | Specific postcode centroid | | M40 | Specific postcode at street/house-number level | | B10 | Sub-locality postcode | | B20 | City centroid | | B30 | Generic postcode centroid | ### Precision and Approximation Levels Describes the spatial precision level and interpolation method of the calculated coordinates. | Code | Side of Street | Approximation | Precision | | --- | --- | --- | --- | | 101 | Single | House number, room level | Punctual, room level | | 102 | Single | House number, floor level | Punctual, floor level | | 103 | Single | House number, stair level | Punctual, stair level | | 104 | Single | House number, building/sub-building | Punctual, building/sub-building | | 105 | Single | House number, complex/building | Punctual | | 111 | Single | House number | Punctual, house-number level | | 113 | Single | House number and 3 exponents | House-number approximation, exponent | | 114 | Single | House number and 5 exponents | House-number approximation, exponent | | 115 | Single | House number and 50 exponents | House-number approximation, exponent | | 116 | Single | House number and over 50 exponents | House-number approximation, exponent | | 117 | Single | House number and no exponents | House-number approximation | | 121 | Same side | 3 house numbers | House-number approximation | | 131 | Same side | 5 house numbers | House-number approximation | | 141 | Same side | 50 house numbers | House-number approximation | | 151 | Same side | Over 50 house numbers | House-number approximation | | 221 | Other side | 3 house numbers | House-number approximation | | 231 | Other side | 5 house numbers | House-number approximation | | 241 | Other side | 50 house numbers | House-number approximation | | 251 | Other side | Over 50 house numbers | House-number approximation | | 261 | Single | Street level, no input house number | Street approximation | | 262 | Single | Street level, input house number out of range | Street approximation | | 263 | Single | Street level, SNC | Street approximation | --- ## Person Quality Indicators Reference codes returned for person, name, and legal entity validation in Egon Validation services. ### Quality Codes Detailed indicators describing name and surname recognition, academic titles, legal forms, and gender alignment. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 601 | Freename with individual | | 1 (Changed) | 602 | Composite academic title not recognized | | 1 (Changed) | 603 | Gender conflicting with name | | 1 (Changed) | 604 | Gender not attributed | | 1 (Changed) | 605 | Wrong input gender | | 1 (Changed) | 606 | Academic title already present | | 1 (Changed) | 607 | Different academic title | | 1 (Changed) | 608 | Wrong academic title | | 1 (Changed) | 609 | Legal form already present | | 1 (Changed) | 610 | Different legal form | | 1 (Changed) | 611 | Wrong legal form | | 1 (Changed) | 612 | Wrong first detail of name | | 1 (Changed) | 613 | Wrong second detail of name | | 1 (Changed) | 614 | Second name not present | | 1 (Changed) | 615 | Second surname not present | | 1 (Changed) | 616 | Forced name | | 1 (Changed) | 617 | CO found | | 1 (Changed) | 618 | Relation not found for name | | 1 (Changed) | 619 | Relation not found for surname | | 1 (Changed) | 620 | Only names found | | 1 (Changed) | 621 | Forced family | | 1 (Changed) | 622 | Too many individuals for sole proprietorship | | 1 (Changed) | 640 | Double freename | | 2/3 (Not valid) | 101 | Name/company name not present | | 2/3 (Not valid) | 102 | Invalid data | | 2/3 (Not valid) | 103 | Invalid data | | 2/3 (Not valid) | 104 | Invalid data | | 2/3 (Not valid) | 105 | Incongruent data | | 2/3 (Not valid) | 106 | Too many input fields | | 2/3 (Not valid) | 107 | Too many numbers | | 2/3 (Not valid) | 108 | Too many details for the name | | 2/3 (Not valid) | 109 | Too many legal forms | | 2/3 (Not valid) | 110 | Too many academic titles | | 2/3 (Not valid) | 111 | Name/company name not recognized | | 2/3 (Not valid) | 112 | Name/company name not recognized | | 2/3 (Not valid) | 113 | Wrong input name | | 2/3 (Not valid) | 114 | Name not present | | 2/3 (Not valid) | 115 | Wrong input surname | | 2/3 (Not valid) | 116 | Surname not present | | 2/3 (Not valid) | 117 | Wrong input middle name | | 2/3 (Not valid) | 118 | Name/company name not recognized | | 2/3 (Not valid) | 119 | Input name not present | | 2/3 (Not valid) | 120 | Input surname not present | | 2/3 (Not valid) | 121 | Too many CO | | 2/3 (Not valid) | 122 | CO wrong format | --- ## Phone Quality Indicators Reference codes returned in `quality.phones` by the Egon Phone validation service. ### Quality Codes Detailed quality indicators describing telephone number formatting, country dial-in additions, area codes, and prefix consistency. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 970 | Format corrected | | 1 (Changed) | 971 | Italian dial-in code added | | 1 (Changed) | 972 | Extra information separated from phone number | | 1 (Changed) | 973 | National dial-in code added | | 1 (Changed) | 974 | Contradictory phone type and prefix | | 1 (Changed) | 975 | Old prefix found | | 1 (Changed) | 976 | International phone found | | 1 (Changed) | 977 | Isolated digits removed | | 1 (Changed) | 978 | Phone number composed by 4 digits | | 1 (Changed) | 979 | Same digit repetition with valid prefix | | 1 (Changed) | 980 | Different phone numbers found | | 1 (Changed) | 981 | Phone type information | | 1 (Changed) | 982 | Missing prefix with ambiguous locality | | 1 (Changed) | 983 | Too many phone numbers | | 1 (Changed) | 984 | International dial-in code added | | 1 (Changed) | 985 | Phone number starting with zero | | 2/3 (Not valid) | 442 | Missing prefix | | 2/3 (Not valid) | 470 | Wrong phone number | | 2/3 (Not valid) | 471 | Phone number not present | | 2/3 (Not valid) | 472 | Phone number 0 | | 2/3 (Not valid) | 473 | Too many numbers | | 2/3 (Not valid) | 474 | Same digit repetition | | 2/3 (Not valid) | 475 | Prefix not found for Country | | 2/3 (Not valid) | 476 | Prefix not congruent with Locality | --- ## Tax Code Quality Indicators Reference codes returned for tax-code calculation, extraction, checking, and matching in Egon Tax Code services. ### Quality Codes Detailed quality indicators describing checksum calculations, birth coherence, omocody substitution, and national identifier consistency. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 901 | Date of birth not present | | 1 (Changed) | 902 | Gender not present | | 1 (Changed) | 903 | Different tax code due to omocodia (digits replaced by letters) | | 1 (Changed) | 904 | Ambiguous characters | | 1 (Changed) | 905 | Uppercase characters | | 1 (Changed) | 906 | Double name | | 1 (Changed) | 907 | Double surname | | 1 (Changed) | 908 | Inverted name and surname | | 1 (Changed) | 909 | Inverted VAT number and tax code | | 1 (Changed) | 998 | Logic error | | 1 (Changed) | 999 | Not processed | | 2/3 (Not valid) | 401 | Code not present | | 2/3 (Not valid) | 402 | Wrong format | | 2/3 (Not valid) | 403 | Wrong code | | 2/3 (Not valid) | 404 | Not numerical | | 2/3 (Not valid) | 405 | Code too long | | 2/3 (Not valid) | 406 | Wrong date of birth | | 2/3 (Not valid) | 407 | Incongruent date of birth | | 2/3 (Not valid) | 408 | Incongruent gender | | 2/3 (Not valid) | 409 | Wrong tax office code | | 2/3 (Not valid) | 410 | Incongruent tax office code | | 2/3 (Not valid) | 411 | Incongruent National Identifier | | 2/3 (Not valid) | 412 | Incongruent VAT number | | 2/3 (Not valid) | 413 | Surname not present | | 2/3 (Not valid) | 414 | Name not present | | 2/3 (Not valid) | 415 | Date of birth not present | | 2/3 (Not valid) | 416 | Gender not present | | 2/3 (Not valid) | 417 | Place of birth not present | | 2/3 (Not valid) | 418 | Wrong check-digit | | 2/3 (Not valid) | 419 | Wrong surname | | 2/3 (Not valid) | 420 | Wrong name | | 2/3 (Not valid) | 421 | Wrong place of birth | | 2/3 (Not valid) | 422 | Inconsistent surname | | 2/3 (Not valid) | 423 | Inconsistent name | | 2/3 (Not valid) | 424 | Wrong month of birth | | 2/3 (Not valid) | 425 | Wrong day of birth | | 2/3 (Not valid) | 426 | Wrong gender | | 2/3 (Not valid) | 427 | Place of birth not found | | 2/3 (Not valid) | 428 | Invalid data | | 2/3 (Not valid) | 429 | Year of birth not numerical | | 2/3 (Not valid) | 430 | Month of birth not numerical | | 2/3 (Not valid) | 431 | Day of birth not numerical | | 2/3 (Not valid) | 432 | Ambiguous place of birth | | 2/3 (Not valid) | 433 | Incongruent place of birth | | 2/3 (Not valid) | 434 | Double name | | 2/3 (Not valid) | 435 | Double surname | | 2/3 (Not valid) | 436 | Cadastral code not found | | 2/3 (Not valid) | 437 | Province code not found | | 2/3 (Not valid) | 438 | Wrong VAT number | | 2/3 (Not valid) | 439 | Not numerical VAT number | | 2/3 (Not valid) | 440 | VAT number not present | | 2/3 (Not valid) | 441 | Mandatory data not present | | 2/3 (Not valid) | 444 | Tax code not present | | 2/3 (Not valid) | 445 | Economy activity code not found | | 2/3 (Not valid) | 446 | Old economy activity code not found | | 2/3 (Not valid) | 447 | VAT number in the tax code field | | 2/3 (Not valid) | 448 | Tax code in the VAT number field | | 2/3 (Not valid) | 449 | Wrong tax office code | --- ## VAT Quality Indicators Reference codes returned for VAT number validation and corporate data extraction in Egon VAT services. ### Quality Codes Detailed quality indicators describing VAT numerical validity, check-digit calculations, country code matching, and economic activity validation. | Flag | Code | Description | | --- | --- | --- | | 0 (OK) | 0 | OK | | 1 (Changed) | 901 | Date of birth not present | | 1 (Changed) | 902 | Gender not present | | 1 (Changed) | 903 | Different tax code due to omocodia (digits replaced by letters) | | 1 (Changed) | 904 | Ambiguous characters | | 1 (Changed) | 905 | Uppercase characters | | 1 (Changed) | 906 | Double name | | 1 (Changed) | 907 | Double surname | | 1 (Changed) | 908 | Inverted name and surname | | 1 (Changed) | 909 | Inverted VAT number and tax code | | 1 (Changed) | 998 | Logic error | | 1 (Changed) | 999 | Not processed | | 2/3 (Not valid) | 401 | Code not present | | 2/3 (Not valid) | 402 | Wrong format | | 2/3 (Not valid) | 403 | Wrong code | | 2/3 (Not valid) | 404 | Not numerical | | 2/3 (Not valid) | 405 | Code too long | | 2/3 (Not valid) | 406 | Wrong date of birth | | 2/3 (Not valid) | 407 | Incongruent date of birth | | 2/3 (Not valid) | 408 | Incongruent gender | | 2/3 (Not valid) | 409 | Wrong tax office code | | 2/3 (Not valid) | 410 | Incongruent tax office code | | 2/3 (Not valid) | 411 | Incongruent National Identifier | | 2/3 (Not valid) | 412 | Incongruent VAT number | | 2/3 (Not valid) | 413 | Surname not present | | 2/3 (Not valid) | 414 | Name not present | | 2/3 (Not valid) | 415 | Date of birth not present | | 2/3 (Not valid) | 416 | Gender not present | | 2/3 (Not valid) | 417 | Place of birth not present | | 2/3 (Not valid) | 418 | Wrong check-digit | | 2/3 (Not valid) | 419 | Wrong surname | | 2/3 (Not valid) | 420 | Wrong name | | 2/3 (Not valid) | 421 | Wrong place of birth | | 2/3 (Not valid) | 422 | Inconsistent surname | | 2/3 (Not valid) | 423 | Inconsistent name | | 2/3 (Not valid) | 424 | Wrong month of birth | | 2/3 (Not valid) | 425 | Wrong day of birth | | 2/3 (Not valid) | 426 | Wrong gender | | 2/3 (Not valid) | 427 | Place of birth not found | | 2/3 (Not valid) | 428 | Invalid data | | 2/3 (Not valid) | 429 | Year of birth not numerical | | 2/3 (Not valid) | 430 | Month of birth not numerical | | 2/3 (Not valid) | 431 | Day of birth not numerical | | 2/3 (Not valid) | 432 | Ambiguous place of birth | | 2/3 (Not valid) | 433 | Incongruent place of birth | | 2/3 (Not valid) | 434 | Double name | | 2/3 (Not valid) | 435 | Double surname | | 2/3 (Not valid) | 436 | Cadastral code not found | | 2/3 (Not valid) | 437 | Province code not found | | 2/3 (Not valid) | 438 | Wrong VAT number | | 2/3 (Not valid) | 439 | Not numerical VAT number | | 2/3 (Not valid) | 440 | VAT number not present | | 2/3 (Not valid) | 441 | Mandatory data not present | | 2/3 (Not valid) | 444 | Tax code not present | | 2/3 (Not valid) | 445 | Economy activity code not found | | 2/3 (Not valid) | 446 | Old economy activity code not found | | 2/3 (Not valid) | 447 | VAT number in the tax code field | | 2/3 (Not valid) | 448 | Tax code in the VAT number field | | 2/3 (Not valid) | 449 | Wrong tax office code | --- ## Domains & Dictionaries Domain dictionaries define the standardized code values and types accepted and returned by Egon request and response fields. ### Domain Dictionaries - [Adm Code Domain](https://documentation.egon.com/docs/domains/adm-code.md): Official administrative code types returned for normalized addresses, including Belfiore, Istat, CAB, Iris, and ISO 3166. (12 values) - [Code Domain](https://documentation.egon.com/docs/domains/code.md): Allowed values for identifier fields such as tax code, VAT code, web address, and Ateco economic activity code. (4 values) - [Email Domain](https://documentation.egon.com/docs/domains/email.md): Classification values for email address types, differentiating standard email and Italian certified PEC. (2 values) - [Name & Person Domain](https://documentation.egon.com/docs/domains/name.md): Subject classification types (natural person, sole proprietorship, legal entity) and gender values. (9 values) - [Phone Domain](https://documentation.egon.com/docs/domains/phone.md): Telecommunication line types returned in enrichment responses (landline, mobile, fax). (3 values) ### Also in Reference Complementary reference guide and data dictionary: - [Quality Indicators](https://documentation.egon.com/docs/quality-indicators.md): Detailed validation flags (0, 1, 2/3) and outcome codes for addresses, geocoding, tax codes, and VAT. --- ## Adm Code Domain Allowed values and meanings for the administrative-code `type` field returned in normalized address payloads. ### Adm Code Types Official administrative authority coding systems supported by Egon. | Field | Data Type | Code | Description | | --- | --- | --- | --- | | type | String | 30000 | Belfiore code | | type | String | 30021 | Istat province + municipality code | | type | String | 30022 | Istat region code | | type | String | 30030 | Locality CAB code | | type | String | 30036 | Iris code | | type | String | 30036-Description | Iris code type # Iris code description | | type | String | 30050 | Bank of Italy code | | type | String | 30060 | UIC code | | type | String | 30061 | Istat state code | | type | String | 30070 | ISO 3166-1 alpha-3 | | type | String | 30071 | ISO 3166-1 alpha-2 | | type | String | 30072 | ISO 3166-1 numeric | --- ## Code Domain Allowed values for code-type fields such as `cod_type` and `type` across Egon validation requests and responses. ### Code Types Classification codes for national identifiers, business registries, and digital addresses. | Field | Data Type | Code | Description | | --- | --- | --- | --- | | type | String | 01110 | Tax code | | type | String | 01111 | VAT code | | type | String | 01116 | Web address | | type | String | 01600 | Ateco Code | --- ## Email Domain Allowed values for the email-address `type` field returned in validation and enrichment responses. ### Email Types Classification codes distinguishing regular email inboxes and certified electronic mail (PEC). | Field | Data Type | Code | Description | | --- | --- | --- | --- | | type | String | 01115 | Email | | type | String | 01601 | Pec | --- ## Name & Person Domain Allowed values for `type_ana` and `gender` fields in name-related validation requests and responses. ### Person Type Allowed values for `type_ana` designating the legal nature of the subject. | Field | Data Type | Code | Description | | --- | --- | --- | --- | | type_ana | String | 1 | Natural person | | type_ana | String | 2 | Sole proprietorship | | type_ana | String | 3 | Legal entity | | type_ana | String | 4 | Co-holder | | type_ana | String | 5 | Family | | type_ana | String | 6 | Unspecified | ### Gender Allowed values for the `gender` field. | Field | Data Type | Code | Description | | --- | --- | --- | --- | | gender | String | 0 | Unspecified | | gender | String | 1 | Male | | gender | String | 2 | Female | --- ## Phone Domain Allowed values for the phone-number `type` field returned in phone validation and enrichment results. ### Phone Types Classification codes distinguishing landlines, mobile numbers, and fax lines. | Field | Data Type | Code | Description | | --- | --- | --- | --- | | type | String | 00001 | Landline | | type | String | 00002 | Mobile | | type | String | 00003 | Fax | --- ## Batch Processing High-throughput asynchronous address normalization and geocoding via SFTP for massive enterprise datasets. ### Architecture & Integration Model Egon **Polling Process Normalization (PPN)** is an automated, file-based engine optimized for processing millions of records without per-row API overhead. Compare the integration models to choose the right approach for your workload: | Architectural Dimension | Batch PPN Engine | Real-Time REST API | | ----------------------- | --------------------------------------------------- | ---------------------------------------------- | | **Transport** | SFTP (paired `.zip` + `.trk` files) | HTTPS REST (JSON / GET / POST) | | **Primary Use Case** | Database cleanups, ERP migrations, data warehouses | Checkout forms, CRM single lookups, web apps | | **Execution** | Asynchronous daemon polling the input folder | Synchronous request-response with low latency | | **Throughput** | Hundreds of thousands to millions of rows per batch | Optimized for individual and small burst calls | | **Data Preservation** | Zero data loss: source columns `0..N` kept intact | Normalized JSON payload structure | --- ### The 3-Step Lifecycle Processing follows an automated lifecycle between your integration and the Egon server: | Phase | Actor / Location | Action | | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **1. Deposit** | Client → `./input/` | Upload `.zip` (containing `.csv`) and its `.trk`, which can stay on the server for later runs. | | **2. Process** | Daemon Engine | A background worker polls `./input/`, picks up each archive with its descriptor, and enriches the records. | | **3. Delivery** | Client ← `./output/` | Engine deposits `_output_.gz` with 32 appended fields (27 with `NOR;`) ready for retrieval and cleanup. | > **Validate Your .trk** > > Want to check your files before configuring SFTP? Use the [Batch > Playground](https://documentation.egon.com/docs/batch/playground.md) to map your CSV columns, generate the > `.trk` descriptor, and validate it before upload. --- ### Documentation Guide Explore the technical specifications and operational workflows: #### Processing Architecture ##### Core Modules & Capabilities - **[SFTP & Workflow](https://documentation.egon.com/docs/batch/sftp-workflow.md)**: Connect over SFTP, deposit paired input archives, and retrieve enriched datasets automatically. - **[Input & TRK Mapping](https://documentation.egon.com/docs/batch/input-specifications.md)**: Delimited data is compressed into `.zip` accompanied by a `.trk` configuration defining country ISO, delimiters, and column indices. - **[Output & Enrichments](https://documentation.egon.com/docs/batch/output-specifications.md)**: The engine standardizes postal addresses across 250+ countries, adds WGS84 coordinates with `GEO;`, and generates enriched `.gz` archives. - **[Batch Playground](https://documentation.egon.com/docs/batch/playground.md)**: Map your CSV columns, generate the `.trk` descriptor, and validate it before upload. --- ## SFTP Setup & Workflow Automate high-volume batch address validation and enrichment over SFTP. Upload `.zip` and its `.trk` descriptor to `./input/`, and retrieve standardized `.gz` datasets from `./output/`. ### Connection Parameters | Parameter | Type | Value / Description | Example | | ------------------ | ----------- | --------------------------- | -------------------------- | | **Host** | Hostname | SFTP server endpoint | Provided during onboarding | | **Port** | Integer | SFTP server port | Provided during onboarding | | **Protocol** | Protocol | SSH File Transfer Protocol | `SFTP` | | **Username** | String | Customer account identifier | Provided during onboarding | | **Authentication** | Credentials | Username and password | Provided during onboarding | --- ### Directory Topology & Processing Lifecycle #### Directory Structure Root directory: `//FTP/` (Username / Password). Dedicated SFTP home directory allocated during onboarding, with full control over `./input` and `./output`. - **`./input/`** (Incoming Processing Mailbox): Deposit dataset archives (`.zip`) and matching descriptor files (`.trk`) into this directory. - Files must share the exact base filename (`.zip` + `.trk`), unless you use a default `.trk` agreed with Egon - The daemon polls this directory for new archives - The `.trk` stays here after processing, so later runs with the same name only need the new `.zip` - **`./output/`** (Results Delivery Mailbox): Retrieve completed, normalized datasets packaged into compressed GZIP archives. - Engine deposits results named `_output_.gz` - Contains original input columns plus normalized postal attributes (geo attributes only with `GEO;`) - Client integration downloads archive and purges remote copy after sync > **Processing Lifecycle** > > 1. **Deposit**: Upload `.zip` and `.trk` to `./input/`. > 2. **Processing**: The daemon polls `./input/` and processes each `.zip` with the `.trk` of the same base name, or with your default `.trk`. > 3. **Delivery**: The completed archive `_output_.gz` is placed into `./output/`, ready for download and cleanup. --- ### File Pairing Each batch job needs an archive and a descriptor: - **`.zip`**: Compressed archive containing exactly one delimited file named `.csv`. It must not contain subfolders or multiple files. - **`.trk`**: Plain-text descriptor declaring input encoding, delimiter, and field-to-column mappings, with the same base name as the archive. It stays in `./input/` after processing, so later runs with the same name only need the new `.zip`. The daemon processes an archive only when a `.trk` with the same base name is in `./input/`, or a default `.trk` is configured. > **Default Descriptor** > > If your column layout is fixed, you can agree a default `.trk` with Egon. It > applies to every archive you upload, even with a different base name, so you > only upload the `.zip`. > **No Error Notifications** > > The engine does not report processing errors. If no output appears in > `./output/`, check that the `.trk` matches the archive and that both files > share the same base name (or that a default `.trk` is configured). --- ### Next Steps - Consult [Input Specifications & TRK Mapping](https://documentation.egon.com/docs/batch/input-specifications.md) for CSV delimiters, encodings, and column index directives. - Consult [Output Schema & Codes](https://documentation.egon.com/docs/batch/output-specifications.md) for the complete dictionary of enriched postal fields and quality flags. --- ## Input Specifications & TRK Mapping CSV formatting rules, ZIP archive packaging, and complete `.trk` column mapping reference. Inbound packages require paired `.zip` (containing a single root `.csv`) and `.trk` files sharing the same base name (unless a default `.trk` is agreed with Egon), with zero-based column indexing and the column delimiter declared in `[IN_SEP]`. ### Packaging Schema #### Input Package Structure - **Compressed Data Archive**: `.zip`, containing `.csv`. Single delimited table (pipe or semicolon separated) - **Configuration Descriptor** (`.trk`): - **[IN_ISO]**: Fixed ISO (ITA) or column index - **[IN_SEP]**: Column delimiter - **[IN_FUN]**: Function: NOR / GEO (includes NOR) - **[IN_...]**: 0-based index (-1 if unmapped) ##### Packaging Rules - **Identical Base Names**: The archive `.zip`, the internal `.csv`, and the descriptor `.trk` must share the exact case-sensitive base name, unless you use a default `.trk` agreed with Egon. - **Single CSV per ZIP**: The `.zip` archive must contain exactly one delimited text file. Nested folders or multiple files inside the zip are rejected. - **Zero-Based Column Indexing**: Field positions declared in the `.trk` file start from index 0 for the first column, 1 for the second column, and so on. - **Matching Character Encoding**: Ensure the text encoding configured via `[IN_ENC]` (e.g. `UTF8` or `cp1252`) strictly matches your source CSV byte encoding. | Component | File Name | Location | Requirements | | ---------------- | ---------------- | -------------- | -------------------------------------------------------------------------- | | **Data Archive** | `.zip` | `./input/` | Standard ZIP archive containing only `.csv`. | | **Data File** | `.csv` | Root of `.zip` | Delimited text file. Header row optional (`[IN_INT]`). | | **Descriptor** | `.trk` | `./input/` | Plain text directive file defining country, delimiter, and column mapping. | > **Recurring Ingestion Jobs** > > The `.trk` stays in `./input/` after processing, so later runs with the same name only need the new `.zip`. If your CSV column layout is fixed, you can also agree a default `.trk` with Egon: it applies to every archive you upload, even with a different base name. --- ### TRK Directives Reference Directives are declared on individual lines using an uppercase bracketed identifier, whitespace padding, and the parameter value terminated by a semicolon (`;`). All column mapping directives use a zero-based column index, or `-1;` when the corresponding column is absent from your input file: ```ini [DIRECTIVE] value; ``` | Directive | Parameter / Component | Allowed Values / Format | Description & CSV Formatting Rules | Example | | ---------- | --------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- | | `[IN_ISO]` | Country | 3-letter ISO (`ITA;`) or column index (`1;`) | Destination country. Alphabetical ISO in single-country runs; 0-based column index in multi-country batches. | `ITA;` or `1;` | | `[IN_FUN]` | Operations | `NOR;`, `GEO;` | `NOR;` normalizes addresses. `GEO;` normalizes and also geocodes. | `GEO;` | | `[IN_SEP]` | CSV Delimiter | `\|;` (Pipe), `$;` (Semicolon) | Column separator character. Recommended: `\|;`. Note: use `$` to declare a semicolon in `.trk`. | `\|;` | | `[IN_ENC]` | Character Encoding | `UTF8;`, `cp1252;`, `cp1250;` | Source file byte encoding. Must match the input CSV encoding. Recommended: `UTF8;`. | `UTF8;` | | `[IN_INT]` | Header Row | `S;` (Present), `N;` (No header row) | When `S;`, row 1 is skipped as column headers. When `N;`, processing starts from row 1. | `S;` | | `[IN_IDN]` | Record Unique ID | Column index or `-1;` | Database primary key, preserved verbatim in its original column. Set to `-1;` if absent. | `0;` | | `[IN_STA]` | Country Name | Column index or `-1;` | Source country name string (e.g. `Italia`). Set to `-1;` when unmapped. | `1;` | | `[IN_REG]` | Region / State | Column index or `-1;` | Administrative territory / region. Set to `-1;` when unmapped. | `2;` | | `[IN_DPT]` | Province Code | Column index or `-1;` | Two-letter official province abbreviation (_Sigla_). Set to `-1;` when unmapped. | `3;` | | `[IN_CNL]` | Municipality / City | Column index or `-1;` | Official municipality name (_Comune_). Set to `-1;` when unmapped, for example when the full address is in `[IN_STR]`. | `4;` | | `[IN_DS1]` | Locality / Hamlet | Column index or `-1;` | Sub-district or hamlet (_Frazione_). Set to `-1;` when unmapped. | `5;` | | `[IN_ZIP]` | Postal Code | Column index or `-1;` | Postal routing code (CAP / ZIP). Set to `-1;` when unmapped. | `6;` | | `[IN_DUG]` | Street Type | Column index or `-1;` | Urban qualifier (_Via, Corso, Viale, Rue, etc._). Set to `-1;` if unmapped. | `7;` | | `[IN_STR]` | Street Name / Address | Column index or `-1;` | Street name. You can also map the full address here, including house number, postal code, and municipality. | `8;` | | `[IN_CIV]` | House Number | Column index or `-1;` | Street building / house number (_Civico_). Set to `-1;` if unmapped. | `9;` | | `[IN_ESP]` | Number Exponent | Column index or `-1;` | House number exponent or suffix (_Esponente / Barrato_). Set to `-1;` if unmapped. | `10;` | | `[IN_PRE]` | Care Of / Interior | Column index or `-1;` | Building interior, care-of, or additional delivery info. Set to `-1;` if unmapped. | `11;` | > **Country Configuration Precedence & ISO Behavior** > > The declared country configuration in your batch job is authoritative and strictly dictates how `[IN_ISO]` is processed. > > **Single-Country Batches (Fixed ISO):** When a specific destination country is declared (e.g. `ITA`, `DEU`, `USA`), `[IN_ISO]` in `.trk` is **always alphabetical** (`[IN_ISO] ITA;`) and applies to all rows uniformly. No CSV column is mapped to `[IN_ISO]`. Even if the input CSV contains an `ISO` or `COD_ISO` column, the batch strictly honors the declared configuration and leaves that column unmapped. > > **Multi-Country Batches (Multi-ISO Column):** When the dataset contains records from multiple nations, `[IN_ISO]` is **numeric** (e.g. `[IN_ISO] 1;`), pointing to the 0-based column index where each row supplies its 3-letter ISO code. In this mode, `[IN_ISO]` cannot be `-1;` (a column mapping is mandatory). --- ### Concrete Examples #### Example 1: Sample CSV Records (`customers_202610.csv`) ```text ID|COUNTRY|REGION|PROVINCE|CITY|LOCALITY|ZIP|STREET_TYPE|STREET_NAME|NUMBER|EXPONENT|CARE_OF 1001|Italia|Lombardia|MI|Milano||20121|Via|Monte Napoleone|8|A|Studio Rossi 1002|Italia|Lazio|RM|Rom|||P.zza|di Spagana|1|| 1003|Italia|Veneto|VR|Verona|San Massimo|37139|Corso|Milano|45|B| ``` #### Example 2: Single-Country Descriptor File (`customers_202610.trk`) In single-country batches, `[IN_ISO]` is alphabetical (`ITA;`), and all 12 column directives are defined: ```ini [IN_ISO] ITA; [IN_FUN] GEO; [IN_SEP] |; [IN_ENC] UTF8; [IN_INT] S; [IN_IDN] 0; [IN_STA] 1; [IN_REG] 2; [IN_DPT] 3; [IN_CNL] 4; [IN_DS1] 5; [IN_ZIP] 6; [IN_DUG] 7; [IN_STR] 8; [IN_CIV] 9; [IN_ESP] 10; [IN_PRE] 11; ``` #### Example 3: Multi-Country Batch with Unmapped Directives (`shipments_eu.trk`) In cross-border datasets, `[IN_ISO]` is numeric (`1;`), pointing to the 0-based column index where the country code is located. Directives for columns not present in the CSV are explicitly configured as `-1;`: ```text ID|ISO|CITY|ZIP|ADDRESS|CIVIC 501|FRA|Paris|75004|rue de Rivoli|45 502|DEU|Berlin|10117|Friedrichstraße|100 503|ESP|Madrid|28013|Calle Gran Vía|28 ``` ```ini [IN_ISO] 1; [IN_FUN] GEO; [IN_SEP] |; [IN_ENC] UTF8; [IN_INT] S; [IN_IDN] 0; [IN_STA] -1; [IN_REG] -1; [IN_DPT] -1; [IN_CNL] 2; [IN_DS1] -1; [IN_ZIP] 3; [IN_DUG] -1; [IN_STR] 4; [IN_CIV] 5; [IN_ESP] -1; [IN_PRE] -1; ``` > **Unmapped Directives Rule** > > Keep all 12 column directives in the `.trk` file. When your input dataset does > not provide a field (such as an ID, province, hamlet, or care-of), set its > directive to `-1;` instead of removing it. > **Try in Playground** > > Want to test your own CSV dataset layout, auto-detect column directives, and > generate validated `.trk` descriptor files interactively? Use the [Batch > Processing Playground](https://documentation.egon.com/docs/batch/playground.md). --- ### Next Steps - Inspect the [Output Schema & Codes](https://documentation.egon.com/docs/batch/output-specifications.md) for the full dictionary of returned fields and coordinates. - Explore the [Quality Indicators Reference](https://documentation.egon.com/docs/quality-indicators.md) for complete diagnostic code definitions. - Upload your files with [SFTP Setup & Workflow](https://documentation.egon.com/docs/batch/sftp-workflow.md). --- ## Output Schema & Codes Complete schema of the enriched output file delivered as GZIP (`.gz`) in `./output/`. Source columns `0..N` are preserved untouched with 32 standardized postal, spatial, and diagnostic match fields appended to the right (27 with `[IN_FUN] NOR;`, which omits the geocoding fields). ### Output Delivery Schema #### Output Archive Format - **Compressed Delivery Archive**: `_output_.gz`, containing `_output_`. Delimited text file containing source fields followed by standardized postal data, WGS84 coordinates (with GEO;), and diagnostic codes. - **SFTP Delivery Channel** (`Delivery Specifications`): - **Target Path**: `./output/` folder - **Compression**: GZIP format (`.gz`) - **Timestamp**: `YYYYMMDDHHMM` - **Delimiter**: Inherited from `[IN_SEP]` ##### Delivery Rules - **Timestamped Delivery**: Appends `_output_` (`YYYYMMDDHHMM`) to ensure unique file versions and prevent overwriting prior executions. - **GZIP Compression (.gz)**: Results are streamed into high-compression GZIP archives to minimize SFTP bandwidth and maximize transfer speeds. - **Preserved Column Order**: Original input columns remain verbatim at positions `0..N`, enabling frictionless reconciliation and database updates. - **Consistent Delimiter**: Output files preserve the exact delimiter declared in `[IN_SEP]` (pipe or semicolon) across all columns. | Delivery Attribute | Value / Format | Description | | ------------------ | ---------------------------------- | ----------------------------------------------------- | | **Directory** | `./output/` | Assigned customer delivery channel. | | **File Pattern** | `_output_.gz` | Timestamp format: `YYYYMMDDHHMM`. | | **Archive Format** | GZIP (`.gz`) | Single compressed delimited text file. | | **Delimiter** | Matches `[IN_SEP]` | Pipe (`\|`) or semicolon (`;`). | | **Encoding** | Matches `[IN_ENC]` | UTF-8 or declared byte encoding. | | **Line Count** | 1:1 with Input | Header row (if enabled) + 1 output row per input row. | > **Custom Output Layout** > > The layout below is the standard one. Like the input `.trk`, the output can be > customized: ask Egon to agree the fields and their order for your account. --- ### Record Composition & Enriched Output Dataset Every output row preserves all source columns `0..N` untouched on the left, appending 32 standardized postal, spatial, persistent ID, and diagnostic fields to the right, or 27 with `[IN_FUN] NOR;`, which omits the 5 geocoding fields. The number of source columns depends on your input file: the example below has 12 and uses `GEO;`, for 44 columns in total. Use the category cards below to jump to detailed field specifications, or explore the complete 44-column dataset in the interactive spreadsheet preview. Use **Copy Spreadsheet (Excel)** to copy and paste directly into Excel or **Copy Output CSV** for raw delimited data: #### Output Record Composition Each line in the processed output file contains these sections, in order: - **Original Input** (Columns 0..N): All source columns from your CSV preserved verbatim in their original positions. - **Normalized Postal** (16 fields): UPU-compliant street, house number, postal code, and municipality. - **Geocoding & Census** (5 fields): WGS84 decimal coordinates, approximation level, coordinate source, and census section. Only with `[IN_FUN] GEO;`. - **Persistent Identifiers** (5 fields): Immutable surrogate integers for clustering, linking, and deduplication. - **Diagnostic Codes** (6 fields): Granular `ERR_620` match confidence and validation status flags. Geocoding fields, in order: `SEZIONE_2011`, `ATT_VLXATT`, `BES_VLXBES`, `BES_1_X_G`, `BES_1_Y_G`. #### Enriched Output Dataset Example (`customers_202610_output_.gz`) Output dataset produced after postal validation, normalization, and geocoding: | ID | COUNTRY | REGION | PROVINCE | CITY | LOCALITY | ZIP | STREET_TYPE | STREET_NAME | NUMBER | EXPONENT | CARE_OF | DSXPLCUFF_DSXCNY | DSXPLCUFF_DSXREG | DSXPLCSIG_DSXDPT | DSXPLCUFF_DSXDPT | DSXPLCUFF_DSXCNL | CDXSTA | DSXPLCUFF_DSXDS1 | CDXZIP | DSXSTRUFF_DSXADD | DSXSTRABB_DSXADD | DSXST1_DSXDUG | DSXST1_DSXVIA | CIVICOST1_NRPNUMCIV | CIVICOST1_DSXESP | DSXEXTURB | DSXPREINR | SEZIONE_2011 | ATT_VLXATT | BES_VLXBES | BES_1_X_G | BES_1_Y_G | CDPOBJDPT | CDPOBJCNL | CDPOBJDS1 | CDPOBJSTR | CDPOBJCIV | ERR_620_LOC_FLXSEG | ERR_620_LOC_CDPSEG | ERR_620_STR_FLXSEG | ERR_620_STR_CDPSEG | ERR_620_CIV_FLXSEG | ERR_620_CIV_CDPSEG | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1001 | Italia | Lombardia | MI | Milano | | 20121 | Via | Monte Napoleone | 8 | A | Studio Rossi | ITALIA | LOMBARDIA | MI | MILANO | MILANO | 015146 | | 20121 | VIA MONTE NAPOLEONE 8 A | VIA MONTE NAPOLEONE 8 A | VIA | MONTE NAPOLEONE | 8 | A | | STUDIO ROSSI | 0151460000071 | 117 | A41 | 9,19569260 | 45,46792182 | 38000000067 | 38000002491 | | 38000052108 | 380100194148637 | 0 | 0 | 0 | 0 | 1 | 502 | | 1002 | Italia | Lazio | RM | Rom | | | P.zza | di Spagana | 1 | | | ITALIA | LAZIO | RM | ROMA | ROMA | 058091 | | 00187 | PIAZZA DI SPAGNA 1 | PIAZZA DI SPAGNA 1 | PIAZZA | DI SPAGNA | 1 | | | | 0580911040006 | 111 | A41 | 12,48131979 | 41,90659832 | 38000000093 | 38000000243 | | 38000087138 | 380100011660401 | 1 | 782 | 1 | 891 | 0 | 0 | | 1003 | Italia | Veneto | VR | Verona | San Massimo | 37139 | Corso | Milano | 45 | B | | ITALIA | VENETO | VR | VERONA | VERONA | 023091 | | 37138 | CORSO MILANO 45 B | CORSO MILANO 45 B | CORSO | MILANO | 45 | B | | | 0230910001173 | 111 | A41 | 10,97183893 | 45,44318244 | 38000000115 | 38000004730 | | 38000072655 | 380100008175361 | 0 | 0 | 1 | 814 | 1 | 503 | --- ### Normalized Postal Fields Official address elements standardized against national postal authorities and Universal Postal Union (UPU) guidelines: | Field Name | Type | Description | Example Value | | --------------------- | -------- | ------------------------------------------------------------------------ | ------------------------- | | `DSXPLCUFF_DSXCNY` | `String` | Official country name | `ITALIA` | | `DSXPLCUFF_DSXREG` | `String` | Official region / administrative territory | `LOMBARDIA` | | `DSXPLCSIG_DSXDPT` | `String` | Official province two-letter abbreviation (_Sigla_) | `MI` | | `DSXPLCUFF_DSXDPT` | `String` | Official province name | `MILANO` | | `DSXPLCUFF_DSXCNL` | `String` | Official municipality name (_Comune_) | `MILANO` | | `CDXSTA` | `String` | Official national statistical code (e.g. ISTAT municipality code) | `015146` | | `DSXPLCUFF_DSXDS1` | `String` | Official locality / hamlet / district (_Frazione_) | — | | `CDXZIP` | `String` | Standardized postal code (CAP / ZIP) | `20121` | | `DSXSTRUFF_DSXADD` | `String` | Complete official street address line | `VIA MONTE NAPOLEONE 8 A` | | `DSXSTRABB_DSXADD` | `String` | Standard abbreviated street line (optimized for envelope windows) | `VIA MONTE NAPOLEONE 8 A` | | `DSXST1_DSXDUG` | `String` | Standardized street type / urban designation (_DUG_) | `VIA` | | `DSXST1_DSXVIA` | `String` | Standardized street name | `MONTE NAPOLEONE` | | `CIVICOST1_NRPNUMCIV` | `String` | Normalized house number | `8` | | `CIVICOST1_DSXESP` | `String` | Normalized house number exponent / suffix (_Esponente / Barrato_) | `A` | | `DSXEXTURB` | `String` | Extra-urban metric or kilometer milestone marker | — | | `DSXPREINR` | `String` | Normalized building, interior, or care-of reference (_Presso / Interno_) | — | --- ### Geocoding & Census Data Appended only when `[IN_FUN]` is `GEO;`: with `NOR;` these 5 columns are omitted from the file. See [Geocoding Quality Indicators](https://documentation.egon.com/docs/quality-indicators/geocoding.md) for the values of `ATT_VLXATT` and `BES_VLXBES`: | Field Name | Type | Description | Example Value | | -------------- | --------- | ------------------------------------------------------------------------- | --------------- | | `SEZIONE_2011` | `String` | Official national census tract code (e.g. ISTAT 2011 section) | `0151460000071` | | `ATT_VLXATT` | `String` | Coordinate approximation level | `117` | | `BES_VLXBES` | `String` | Coordinate source | `A41` | | `BES_1_X_G` | `Decimal` | Longitude in WGS84 decimal degrees, with a comma as the decimal separator | `9,19569260` | | `BES_1_Y_G` | `Decimal` | Latitude in WGS84 decimal degrees, with a comma as the decimal separator | `45,46792182` | --- ### Persistent Egon Identifiers Immutable surrogate numeric keys assigned to territorial entities in the Egon master database: | Field Name | Type | Entity Level | Purpose | Example Value | | ----------- | ------ | ------------ | ------------------------------------------- | ----------------- | | `CDPOBJDPT` | `Long` | Province | Grouping by administrative province | `38000000067` | | `CDPOBJCNL` | `Long` | Municipality | Grouping by city (_Comune_) | `38000002491` | | `CDPOBJDS1` | `Long` | Locality | Grouping by hamlet (_Frazione_) | — | | `CDPOBJSTR` | `Long` | Street | Exact street entity deduplication | `38000052108` | | `CDPOBJCIV` | `Long` | House Number | Building-level deduplication and clustering | `380100194148637` | --- ### Quality & Diagnostic Indicators Validation flags evaluating match outcome and changes across administrative tiers. See [Address Quality Indicators](https://documentation.egon.com/docs/quality-indicators/address.md) for the meaning of each flag and code: | Field Name | Type | Evaluated Level | Description | Example Value | | -------------------- | -------- | --------------- | ----------------------------------- | ------------- | | `ERR_620_LOC_FLXSEG` | `String` | Locality / City | Reporting flag for the locality | `0` | | `ERR_620_LOC_CDPSEG` | `String` | Locality / City | Reporting code for the locality | `0` | | `ERR_620_STR_FLXSEG` | `String` | Street | Reporting flag for the street | `0` | | `ERR_620_STR_CDPSEG` | `String` | Street | Reporting code for the street | `0` | | `ERR_620_CIV_FLXSEG` | `String` | House Number | Reporting flag for the house number | `1` | | `ERR_620_CIV_CDPSEG` | `String` | House Number | Reporting code for the house number | `502` | --- ### Next Steps - Map your CSV columns and validate your `.trk` descriptor in the [Batch Playground](https://documentation.egon.com/docs/batch/playground.md). - Configure automated file transfers in [SFTP Setup & Workflow](https://documentation.egon.com/docs/batch/sftp-workflow.md). --- ## Batch Processing Playground The interactive Batch Processing Playground validates and corrects your `.trk` descriptor before you upload it, so the batch runs without mapping errors. It does not process records or produce output. | Step | Description | | --- | --- | | 1. Input & Mapping | Load a sample dataset or your own CSV (pipe or semicolon), then map each column to a `.trk` directive manually or with auto-detection. | | 2. TRK Generation & Validation | Compile the `.trk` descriptor, check it for errors (for example a missing `[IN_ISO]` column in multi-country batches) and download it once it is valid. | --- ## Build with AI Give your AI assistant, coding agent, or app builder the **Egon documentation and OpenAPI schema**, so it writes integrations that match the real API. ### In This Section - [Resources](https://documentation.egon.com/docs/build-with-ai/resources.md): the machine-readable files every build publishes, such as `llms.txt` and the OpenAPI schema. - [Chat Assistants](https://documentation.egon.com/docs/build-with-ai/chat-assistants.md): ask ChatGPT, Claude, or Cursor about the API. - [Coding Agents](https://documentation.egon.com/docs/build-with-ai/coding-agents.md): set up Claude Code, Cursor, GitHub Copilot, or Codex to write Egon code. - [Agent Skills](https://documentation.egon.com/docs/build-with-ai/skills.md): install the Egon skills in Claude Code, Codex, Cursor, and other coding agents. - [App Builders](https://documentation.egon.com/docs/build-with-ai/app-builders.md): add Egon to apps built with Lovable, v0, or Bolt. - [Prompt Library](https://documentation.egon.com/docs/build-with-ai/prompt-library.md): ready-made prompts for common Egon integrations. - [API Key Safety](https://documentation.egon.com/docs/build-with-ai/api-key-safety.md): keep your key out of prompts and out of the browser. --- ## Resources for AI Every build publishes the documentation, the OpenAPI schema, and the agent skills in **formats an AI tool can read** directly. ### Download Files Give these files to your AI assistant or coding agent. `llms.txt` indexes every page, `llms-full.txt` holds the whole documentation, the OpenAPI schema describes every endpoint, and the [agent skills](https://documentation.egon.com/docs/build-with-ai/skills.md) teach a coding agent how to call Egon and run a batch job. #### LLM Files - [llms.txt](https://documentation.egon.com/llms.txt) - [llms-full.txt](https://documentation.egon.com/llms-full.txt) #### OpenAPI Schema - [openapi.json](https://documentation.egon.com/openapi.json) - [openapi.yaml](https://documentation.egon.com/openapi.yaml) For a single service family, download its schema from the [API Reference](https://documentation.egon.com/docs/api.md#openapi-schema). ### Which File to Use Add the site domain to each path. | Path | Content | Use it when | | -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------- | | `/llms.txt` | Index of every page, with a link to its markdown version | The assistant should find the pages it needs | | `/llms-full.txt` | The whole documentation in one markdown file | You want to load everything at once | | `.md` | Markdown version of a page: add `.md` to any page URL | You work on a single endpoint | | `/openapi.json`, `/openapi.yaml` | The full OpenAPI schema | You generate a client or typed models | | `/openapi/.json` | The OpenAPI schema of one service family, also in `.yaml` | You need one family and a smaller context | | `/skills//SKILL.md` | An agent skill, see [Agent Skills](https://documentation.egon.com/docs/build-with-ai/skills.md) | Your coding agent should load the Egon rules on its own | --- ## Chat Assistants Ask **ChatGPT, Claude, or Cursor** about the Egon API, with the documentation as context. ### Ask About One Page On any page, open **Copy for AI** and choose **Open in ChatGPT**, **Open in Claude**, or **Open in Cursor**. The chat starts with a link to the markdown version of that page. If the assistant cannot open links, choose **Markdown** in the same menu and paste the page in the chat. ### Ask About the Whole API Paste this prompt in a new chat: ```text Read https://documentation.egon.com/llms.txt. It lists the Egon API documentation. Answer my questions using those pages and link the page you used. ``` --- ## Coding Agents Set up **Claude Code, Cursor, GitHub Copilot, or Codex** to write code that matches the Egon API. ### Add the Project Instructions Coding agents read an instructions file in your repository. Add this block to `AGENTS.md` (Codex, Cursor, GitHub Copilot) or `CLAUDE.md` (Claude Code): ```text ## Egon API - Documentation index: https://documentation.egon.com/llms.txt (add .md to any page URL for its markdown) - OpenAPI schema: https://documentation.egon.com/openapi.json - Authentication: use the header described in securitySchemes in the schema. - Read the API key from the EGON_API_KEY environment variable. Never hardcode it and never call Egon from the browser. - Check the quality indicators in each response before trusting the data: https://documentation.egon.com/docs/quality-indicators.md ``` ### Generate a Client Then ask for what you need, for example: ```text Using the Egon OpenAPI schema at https://documentation.egon.com/openapi.json, write a typed TypeScript client for the endpoints this project uses. ``` For prompts on specific integrations, see the [Prompt Library](https://documentation.egon.com/docs/build-with-ai/prompt-library.md). To give your agent the same rules as an installable skill, see [Agent Skills](https://documentation.egon.com/docs/build-with-ai/skills.md). --- ## Agent Skills Install the **Egon skills** once, and your coding agent knows where the documentation is, how to authenticate, how to run a batch job, and how to keep your data safe. Each skill is a single `SKILL.md` file that links to the markdown pages of this site, and `egon-api` also to the OpenAPI schema, so the agent always reads the current documentation. ### The `egon-api` Skill The `egon-api` skill gives your agent the base URL, the authentication header, the key safety rules, and every service of the Egon API. ### The `egon-batch` Skill The `egon-batch` skill teaches your agent how Egon Batch works on this site: how to prepare the address file, run the job, and read the output, with links to every Batch page. ### Install with the Skills CLI Run this in your project. The CLI asks which skills and agents to set up, then copies each skill into the folder each agent reads. ```bash npx skills add https://documentation.egon.com ``` The CLI finds the skills through `/.well-known/agent-skills/index.json`, which every build of this site publishes. ### Install Manually Copy each `SKILL.md` into a folder named after its skill: | Agent | Folder | | ----------------------------------------------------------- | ------------------------ | | Claude Code | `.claude/skills//` | | Codex, Cursor, and other agents that read `.agents/skills/` | `.agents/skills//` | For Claude Code, run this in your project. For other agents, replace `.claude` with `.agents`. ```bash mkdir -p .claude/skills/egon-api && curl -fsSLo .claude/skills/egon-api/SKILL.md https://documentation.egon.com/skills/egon-api/SKILL.md mkdir -p .claude/skills/egon-batch && curl -fsSLo .claude/skills/egon-batch/SKILL.md https://documentation.egon.com/skills/egon-batch/SKILL.md ``` ### Check the Setup Start a new session and ask: ```text Do you have the egon-api and egon-batch skills? Show the base URL and the authentication header the egon-api skill tells you to use, and the steps the egon-batch skill gives to run a batch job. ``` To add Egon to your project instructions instead, see [Coding Agents](https://documentation.egon.com/docs/build-with-ai/coding-agents.md). --- ## App Builders Add Egon services to apps built with **Lovable, v0, or Bolt**. ### How It Works App builders generate a whole app from a prompt. Give them the Egon documentation and the OpenAPI schema in the prompt, and they write the calls for you. 1. Store your API key as a secret named `EGON_API_KEY` in the builder's settings. 2. Copy a prompt from the [Prompt Library](https://documentation.egon.com/docs/build-with-ai/prompt-library.md) and paste it in the builder's chat. The prompts ask for a server-side function, because a key used in the browser is visible to anyone: keep that line when you adapt them (see [API Key Safety](https://documentation.egon.com/docs/build-with-ai/api-key-safety.md)). 3. Test the result with real addresses before you publish the app. --- ## Prompt Library **Ready-made prompts** for common Egon integrations. Paste them in a coding agent or an app builder. ### Real-Time API #### Address Autocomplete ```text Add address autocomplete to the address form using the Egon API. Docs: https://documentation.egon.com/llms.txt OpenAPI: https://documentation.egon.com/openapi.json - Call Egon from a server-side function, never from the browser. - Store the API key as a secret named EGON_API_KEY. - Show suggestions while the user types, after 3 characters, with a 300 ms debounce. - Fill the form fields from the selected suggestion. ``` #### Address Validation on Submit ```text Validate the shipping address with the Egon API when the user submits the checkout form. Docs: https://documentation.egon.com/llms.txt OpenAPI: https://documentation.egon.com/openapi.json - Call Egon from a server-side function, never from the browser. - Store the API key as a secret named EGON_API_KEY. - If Egon returns a corrected address, show it and let the user accept it or keep their own. - Decide whether the address is valid from the quality indicators: https://documentation.egon.com/docs/quality-indicators.md ``` --- ## API Key Safety AI tools make it easy to **leak an API key**. Keep it out of prompts and out of the browser. ### Rules - Never paste a real key into a chat or a prompt. Use `YOUR_API_KEY` or the name of an environment variable. - Call Egon from your server. A key sent from the browser is visible to anyone who opens the page. - Store the key in an environment variable or in your platform's secrets, such as `EGON_API_KEY`. ### Review Generated Code Before you deploy code written by an AI tool, check that: - the key is read from a secret, not written in the code; - no request to Egon starts from the browser; - responses are checked against the [Quality Indicators](https://documentation.egon.com/docs/quality-indicators.md) before the data is used.