{ "openapi": "3.1.0", "info": { "title": "Egon API Reference", "version": "1.0.0", "description": "Suggest, validate, and normalize addresses and related data. Every service is a `POST` endpoint that accepts and returns JSON.", "contact": { "name": "Egon", "url": "https://www.egon.com", "email": "info@egon.com" } }, "externalDocs": { "description": "Egon API documentation", "url": "https://documentation.egon.com" }, "servers": [ { "url": "https://{host}:{port}/Egon", "variables": { "host": { "default": "localhost" }, "port": { "default": "8080" } }, "description": "Replace `{host}` and `{port}` with the address of your Egon instance." } ], "security": [ { "tokenAuth": [] } ], "tags": [ { "name": "Suggest Services", "description": "Predictive autocomplete for countries, cities, streets, postal codes, and house numbers. Results update as you type, so users enter valid addresses." }, { "name": "Validation Services", "description": "Validation and normalization of addresses, names, phones, emails, tax codes, and VAT numbers. Every result has quality flags and codes." }, { "name": "Single Line Service", "description": "Recognition and normalization of a complete address written as a single free-text string. Returns a list of normalized candidates to choose from." }, { "name": "Reverse Geocoding", "description": "Conversion of geographic coordinates into normalized addresses. Returns the nearest house numbers with street, postal code, and distance." }, { "name": "Map Broker Services", "description": "Route calculation and distance matrix services. The Routing endpoint calculates routes for a generic vehicle or for pedestrians." } ], "paths": { "/api/suggest/country": { "post": { "operationId": "country", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, extraction limits, and country query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestCountry" }, "example": { "data": { "query": "Ital" } } } } }, "responses": { "200": { "description": "Matching country candidates, ISO codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseCountry" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching country candidates, ISO codes, and system status.", "value": { "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" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Country", "description": "The Suggest Country endpoint provides predictive autocomplete and search over **world countries**, with names in many languages, ISO codes, and Egon IDs." } }, "/api/suggest/state": { "post": { "operationId": "state", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, country context, and state search query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestQuery" }, "example": { "par": { "iso3": "USA" }, "data": { "query": "ma" } } } } }, "responses": { "200": { "description": "Matching state candidates, administrative codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseState" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching state candidates, administrative codes, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest State", "description": "The Suggest State endpoint provides predictive autocomplete and search for **states and federal states**, returning names, codes, and Egon IDs." } }, "/api/suggest/region": { "post": { "operationId": "region", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, country context, and region search query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestQuery" }, "example": { "par": { "iso3": "ITA" }, "data": { "query": "v" } } } } }, "responses": { "200": { "description": "Matching region candidates, administrative codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseRegion" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching region candidates, administrative codes, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Region", "description": "The Suggest Region endpoint provides predictive autocomplete and search for **regions**, returning each matching region with its name and Egon ID." } }, "/api/suggest/province": { "post": { "operationId": "province", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, country context, and province search query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestRestrictId" }, "example": { "par": { "iso3": "ITA" }, "data": { "query": "Ver" } } } } }, "responses": { "200": { "description": "Matching province candidates, administrative codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseProvince" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching province candidates, administrative codes, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Province", "description": "The Suggest Province endpoint provides predictive autocomplete and search for **provinces**, returning each match with its province code and Egon ID." } }, "/api/suggest/city": { "post": { "operationId": "city", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, country context, and city search query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestRestrictId" }, "example": { "par": { "iso3": "ITA" }, "data": { "query": "Roveredo" } } } } }, "responses": { "200": { "description": "Matching city candidates, administrative hierarchy, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseCity" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching city candidates, administrative hierarchy, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest City", "description": "The Suggest City endpoint provides predictive autocomplete and search for **cities and municipalities**, with their postal code and Egon ID." } }, "/api/suggest/district1": { "post": { "operationId": "district1", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, city ID context, and district query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestRestrictId" }, "example": { "par": { "iso3": "ITA" }, "data": { "query": "Rovaio" } } } } }, "responses": { "200": { "description": "Matching district candidates, administrative hierarchy, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseDistrict1" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching district candidates, administrative hierarchy, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest District 1", "description": "The Suggest District 1 endpoint provides predictive autocomplete and search for **first-level districts**, such as localities and municipalities." } }, "/api/suggest/zipcode": { "post": { "operationId": "zipcode", "tags": ["Suggest Services"], "requestBody": { "description": "Country context, extraction level, and postal code query.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestZipCode" }, "examples": { "localityLevel": { "summary": "Locality level (ITA)", "description": "Locality-level extraction, the default level.", "value": { "par": { "iso3": "ITA" }, "data": { "query": "37135" } } }, "streetLevel": { "summary": "Street level (GBR)", "description": "Street-level extraction, which returns streets, buildings, and organizations for the postal code.", "value": { "par": { "iso3": "GBR" }, "data": { "query": "SL0 9DL", "zip_level": "S" } } } } } } }, "responses": { "200": { "description": "Matching postal codes, associated localities or streets, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseZipCode" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching postal codes, associated localities or streets, and system status.", "value": { "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" } } }, "validStreetLevel": { "summary": "Valid response, street level (GBR)", "description": "Street-level candidates for a GBR postal code, with buildings and organizations, followed by the postal district.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Zipcode", "description": "The Suggest Zipcode endpoint suggests **postal codes** at locality level (`L`) or at street level (`S`, available for GBR, IRL, NLD, and JPN)." } }, "/api/suggest/zipcodeAll": { "post": { "operationId": "zipcodeAll", "tags": ["Suggest Services"], "requestBody": { "description": "Processing options, entity ID, and house-number parameters.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestZipCodeAll" }, "example": { "par": { "iso3": "ITA" }, "data": { "street_id": "38000093621" } } } } }, "responses": { "200": { "description": "House-number range results, parity codes, postal codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseZipCodeAll" }, "examples": { "valid": { "summary": "Valid response", "description": "House-number range results, parity codes, postal codes, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Zipcode All", "description": "The Suggest Zipcode All endpoint returns every **house-number range** for a city, street, or house number, with its parity and range type." } }, "/api/suggest/street": { "post": { "operationId": "street", "tags": ["Suggest Services"], "requestBody": { "description": "City context (`restrict_id`), street query, and output options.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestStreet" }, "example": { "par": { "iso3": "ITA" }, "data": { "query": "Via Pac", "restrict_id": 38000004730 } } } } }, "responses": { "200": { "description": "Matching street candidates, street codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseStreet" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching street candidates, street codes, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "The query field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingRestrictId": { "summary": "Missing restrict ID", "description": "The restrict_id field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "restrict_id not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Street", "description": "The Suggest Street endpoint provides predictive autocomplete for **street search**. The `restrict_id` parameter (city ID) is required." } }, "/api/suggest/hn": { "post": { "operationId": "hn", "tags": ["Suggest Services"], "requestBody": { "description": "Street ID context (`restrict_id`), house-number query, and options.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestHouseNumber" }, "example": { "par": { "iso3": "ITA" }, "data": { "number": "4", "restrict_id": 38000073526 } } } } }, "responses": { "200": { "description": "Matching house numbers, exponents, parity, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseHouseNumber" }, "examples": { "valid": { "summary": "Valid response", "description": "Matching house numbers, exponents, parity, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingNumber": { "summary": "Missing number", "description": "The number field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "number not found" } } }, "missingRestrictId": { "summary": "Missing restrict ID", "description": "The restrict_id field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "restrict_id not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest House Number", "description": "The Suggest House Number endpoint suggests **house numbers** for a street, including numbers with exponents and kilometer markers." } }, "/api/suggest/birthLocality": { "post": { "operationId": "birthLocality", "tags": ["Suggest Services"], "requestBody": { "description": "Search query and optional birth date filtering.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequestBirthLocality" }, "example": { "par": { "function": "official", "level": 5 }, "data": { "locality": "Viter" } } } } }, "responses": { "200": { "description": "Birth locality candidate list, Belfiore codes, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponseBirthLocality" }, "examples": { "valid": { "summary": "Valid response", "description": "Birth locality candidate list, Belfiore codes, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The par object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingData": { "summary": "Missing data", "description": "The data object is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "The token request header is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The token is invalid.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Suggest Birth Locality", "description": "The Suggest Birth Locality endpoint searches official and historical **birth localities** and returns the corresponding Belfiore code." } }, "/api/norm#address": { "post": { "operationId": "address", "tags": ["Validation Services"], "summary": "Address", "description": "The Address endpoint validates and normalizes an address, returning the street, house number, postal data, Egon codes, and geographic coordinates.", "requestBody": { "description": "Country context, processing options, and address fields to validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationAddressRequest" }, "example": { "par": { "iso3": "ITA", "geo": "S" }, "data": { "address": { "city": "Verona", "street": "Via pacinotti 4b" } } } } } }, "responses": { "200": { "description": "Normalized address, geocoding coordinates, postal format, quality indicators, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationAddressResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "The address was processed successfully. Returns normalized address levels, geocoding coordinates, and quality flags.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#email": { "post": { "operationId": "email", "tags": ["Validation Services"], "summary": "Email", "description": "Validate one or more email addresses and return normalized values together with syntax and domain quality indicators.", "requestBody": { "description": "Country context and collection of email addresses to validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationEmailRequest" }, "example": { "par": { "iso3": "ITA" }, "data": { "emails": [ { "email": "info@egon.com" }, { "email": "info@example.com" } ] } } } } }, "responses": { "200": { "description": "Normalized email addresses, validation quality indicators, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationEmailResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Email addresses verified for correct syntax and domain structure.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#name": { "post": { "operationId": "name", "tags": ["Validation Services"], "summary": "Name", "description": "Validate personal names, sole proprietorships, company names, co-holder names, and family surnames, and return normalized and structured output.", "requestBody": { "description": "Country context and person or company name string to validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationNameRequest" }, "example": { "par": { "iso3": "ITA" }, "data": { "name": { "full_name": "Dottor Mario Rossi" } } } } } }, "responses": { "200": { "description": "Structured name components, recognized gender, separated title/surname/name, and quality indicators.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationNameResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Name successfully recognized, titles separated, and structured into first name and surname.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#phone": { "post": { "operationId": "phone", "tags": ["Validation Services"], "summary": "Phone", "description": "Validate and normalize telephone numbers provided either as individual international and national prefix components or as a single full number.", "requestBody": { "description": "Country context and telephone numbers to normalize and validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationPhoneRequest" }, "example": { "par": { "iso3": "ITA" }, "data": { "phones": [ { "pre_int": "39", "pre_nat": "045", "number": "8200794" }, { "number": "390458201847" } ] } } } } }, "responses": { "200": { "description": "Normalized phone numbers with country prefixes, line type codes, quality indicators, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationPhoneResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Phone numbers validated, separated into international and national prefixes, and standardized.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-calc": { "post": { "operationId": "tax-code-calc", "tags": ["Validation Services"], "summary": "Tax Code Calculation", "description": "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.", "requestBody": { "description": "Country context, `taxfnx` function `3`, and personal identity data.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCalcRequest" }, "example": { "par": { "iso3": "ITA", "taxfnx": "3" }, "data": { "name": { "full_name": "Rossi", "first_name": "Mario", "gender": "1", "birth_date": "19930219", "birth_place": "Verona" } } } } } }, "responses": { "200": { "description": "Calculated tax code, quality indicators for personal identity fields, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCalcResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Tax code calculated successfully from personal information.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-check": { "post": { "operationId": "tax-code-check", "tags": ["Validation Services"], "summary": "Tax Code Validation", "description": "Check the formal validity and structure of an Italian tax code (Codice Fiscale) and get a quality flag and code that describe the result.", "requestBody": { "description": "Country context, `taxfnx` function `2`, and tax code to check.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCheckRequest" }, "example": { "par": { "iso3": "ITA", "taxfnx": "2" }, "data": { "tax_code": { "cod_iso3": "ITA", "cod_type": "01110", "cod_description": "RSSMRA93B19L781K" } } } } } }, "responses": { "200": { "description": "Validated tax code, extraction verification quality indicator, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCheckResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Tax code verified and found formally valid.", "value": { "data": { "tax_code": { "cod_description": "RSSMRA93B19L781K" } }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" } }, "system": { "ret_code": 0, "des_ret_code": "Ok" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-extract": { "post": { "operationId": "tax-code-extract", "tags": ["Validation Services"], "summary": "Tax Code Extraction", "description": "Extract gender, date of birth, and place of birth (city and province) from an Italian tax code (Codice Fiscale), with a quality flag.", "requestBody": { "description": "Country context, `taxfnx` function `5`, and tax code to decode.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeExtractRequest" }, "example": { "par": { "iso3": "ITA", "taxfnx": "5" }, "data": { "tax_code": { "cod_iso3": "ITA", "cod_type": "01110", "cod_description": "RSSMRA93B19L781K" } } } } } }, "responses": { "200": { "description": "Extracted birth date, birth province, birth city, quality indicator, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeExtractResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Birth details and province extracted successfully from the tax code.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-match": { "post": { "operationId": "tax-code-match", "tags": ["Validation Services"], "summary": "Tax Code Verification", "description": "Compare a tax code against a person's identifying data, including name, gender, date of birth, and birthplace.", "requestBody": { "description": "Country context, `taxfnx` function `1`, personal identity data, and tax code to compare.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeMatchRequest" }, "example": { "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" } } } } } }, "responses": { "200": { "description": "Normalized personal data, tax code, comparison quality results for identity, birth date, birthplace, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeMatchResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Tax code matches personal information completely.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#vat-check": { "post": { "operationId": "vat-check", "tags": ["Validation Services"], "summary": "VAT Validation", "description": "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.", "requestBody": { "description": "Country context and VAT number to validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatCheckRequest" }, "example": { "par": { "iso3": "ITA" }, "data": { "vat_number": { "cod_iso3": "ITA", "cod_type": "01111", "cod_description": "10851310960" } } } } } }, "responses": { "200": { "description": "Validated VAT number, verification quality indicator, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatCheckResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "VAT number validated and found formally correct.", "value": { "data": { "vat_number": { "cod_description": "10851310960" } }, "quality": { "vat_number": { "flag": "0", "code": 0, "description": "Ok" } }, "system": { "ret_code": 0, "des_ret_code": "Ok" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#vat-ext": { "post": { "operationId": "vat-ext", "tags": ["Validation Services"], "summary": "VAT Extraction", "description": "Validate and enrich company data from a VAT number: official business name, legal address, phone numbers, PEC email, and ATECO codes.", "requestBody": { "description": "Country context, `vatfnx` function `E`, and VAT number to enrich.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatExtRequest" }, "example": { "par": { "iso3": "ITA", "vatfnx": "E" }, "data": { "vat_number": { "cod_description": "01032450072" } } } } } }, "responses": { "200": { "description": "Enriched company profile including business name, tax code, address, phones, emails, activity codes, and quality indicator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatExtResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Company information enriched from VAT number.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/revGeo": { "post": { "operationId": "reverse", "tags": ["Reverse Geocoding"], "requestBody": { "description": "Geographic coordinates (latitude, longitude), radius, and search options.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseRequestJson" }, "example": { "par": { "iso3": "ITA" }, "data": { "longitude": 10.97382316, "latitude": 45.406161 } } } } }, "responses": { "200": { "description": "Nearest address candidates, distance, administrative hierarchy, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseResponseJson" }, "examples": { "valid": { "summary": "Valid response", "description": "Nearest address candidates, distance, administrative hierarchy, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not a valid ISO 3166-1 alpha-3 country code.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Address from Coordinates", "description": "The Reverse geocoding service retrieves **address candidates** from geographic coordinates, with street, house number, postal code, and distance." } }, "/api/single-line/full-address": { "post": { "operationId": "full-address", "tags": ["Single Line Service"], "requestBody": { "description": "Single-line query string, country context, and parsing options.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullAddressRequestFullAddress" }, "example": { "par": { "iso3": "ITA" }, "data": { "query": "Via Pacinotti 4b, Verona" } } } } }, "responses": { "200": { "description": "Structured address candidates, matching confidence scores, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullAddressResponseFullAddress" }, "examples": { "valid": { "summary": "Valid response", "description": "Structured address candidates, matching confidence scores, and system status.", "value": { "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" } } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": { "ret_code": 1, "des_ret_code": "par not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not a valid ISO 3166-1 alpha-3 country code.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingQuery": { "summary": "Missing query", "description": "Provide a non-empty free-text address in the data.query field.", "value": { "system": { "ret_code": 1, "des_ret_code": "query not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } }, "summary": "Full Address", "description": "The Full Address endpoint parses a complete address written as a single free-text string and returns a list of **normalized candidate addresses**." } }, "/api/routes": { "servers": [ { "url": "https://{host}:{port}/EgonMbk", "variables": { "host": { "default": "localhost" }, "port": { "default": "8080" } }, "description": "Replace `{host}` and `{port}` with the address of your Egon Map Broker instance." } ], "post": { "operationId": "routing", "tags": ["Map Broker Services"], "summary": "Routing", "description": "Calculate a route between an origin and a destination for a generic vehicle or a pedestrian, based on the HERE Routing API v8.\n\nTo 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).", "parameters": [ { "name": "transportMode", "in": "query", "required": true, "description": "Mode of transport: `car`, `truck`, `pedestrian`, `bicycle`, `scooter`, `taxi`, `bus`, `privateBus`, or `networkRestrictedTruck`.", "schema": { "type": "string", "enum": [ "car", "truck", "pedestrian", "bicycle", "scooter", "taxi", "bus", "privateBus", "networkRestrictedTruck" ], "default": "car" }, "example": "car" }, { "name": "origin", "in": "query", "required": true, "description": "Origin waypoint (WGS84). Format: `{lat},{lng}`.", "schema": { "type": "string" }, "example": "44.9741733,7.7232365" }, { "name": "destination", "in": "query", "required": true, "description": "Destination waypoint (WGS84). Format: `{lat},{lng}`.", "schema": { "type": "string" }, "example": "43.87644,11.11885" }, { "name": "via", "in": "query", "required": false, "description": "Via waypoint(s). Multiple values are allowed and are traversed sequentially in the specified order.", "schema": { "type": "string" } }, { "name": "routingMode", "in": "query", "required": false, "description": "Route optimization: `fast` (default) or `short`.", "schema": { "type": "string", "enum": ["fast", "short"], "default": "fast" } }, { "name": "return", "in": "query", "required": false, "description": "Attributes to include in the response, including `polyline`, `actions`, `instructions`, `summary`, `travelSummary`, `turnByTurnActions`, `elevation`, `routeHandle`, `incidents`, and `tolls`.", "schema": { "type": "string" } }, { "name": "spans", "in": "query", "required": false, "description": "Map content attributes to include per span. Requires `return=polyline`.", "schema": { "type": "string" } }, { "name": "units", "in": "query", "required": false, "description": "Units of measurement: `metric` (default) or `imperial`.", "schema": { "type": "string", "enum": ["metric", "imperial"], "default": "metric" } }, { "name": "lang", "in": "query", "required": false, "description": "Preferred response language in BCP 47 format, for example `it,en-US`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calculated routes and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapBrokerResponseRoutes" }, "examples": { "valid": { "summary": "Valid response", "description": "Route successfully calculated between origin and destination.", "value": { "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" } } }, "missingParameters": { "summary": "Missing parameters", "description": "Parameters are missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "Invalid request" } } }, "IncompleteParameters": { "summary": "Incomplete parameters", "description": "Parameters are incomplete.", "value": { "system": { "ret_code": 1, "des_ret_code": "Malformed request" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } } }, "components": { "securitySchemes": { "tokenAuth": { "type": "apiKey", "in": "header", "name": "token", "description": "Authentication token sent in the `token` request header." } }, "schemas": { "SuggestRequestQuery": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestPar", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataQuery", "description": "Search criteria and query parameters" } } }, "SuggestRequestCountry": { "type": "object", "required": ["data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestParCountry", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataQuery", "description": "Search criteria and query parameters" } } }, "SuggestRequestRestrictId": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestPar", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataRestrictId", "description": "Search criteria and query parameters" } } }, "SuggestRequestStreet": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestPar", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataRestrictIdMandatory", "description": "Search criteria and query parameters" } } }, "SuggestRequestHouseNumber": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestParHouseNumber", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataRestrictIdMandatoryHouseNumber", "description": "Search criteria and query parameters" } } }, "SuggestRequestBirthLocality": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestParBirthLocality", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataBirthLocality", "description": "Search criteria and query parameters" } } }, "SuggestRequestZipCode": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestPar", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataZipCode", "description": "Search criteria and query parameters" } } }, "SuggestRequestZipCodeAll": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/SuggestPar", "description": "Processing parameters, candidate limits, and country context" }, "data": { "$ref": "#/components/schemas/SuggestDataZipCodeAll", "description": "Search criteria and query parameters" } } }, "SuggestPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "max_candidates": { "type": "number", "default": 10, "description": "Maximum number of candidates to extract" } }, "description": "Processing parameters, candidate limits, and country context" }, "SuggestParCountry": { "type": "object", "properties": { "max_candidates": { "type": "number", "default": 10, "description": "Maximum number of candidates to extract" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" } }, "description": "Processing parameters and output language for country search" }, "SuggestParHouseNumber": { "allOf": [ { "$ref": "#/components/schemas/SuggestPar" }, { "type": "object", "properties": { "certified_only": { "type": "boolean", "default": false, "description": "Return only certified house numbers. Default: `false`" } } } ], "description": "Processing parameters for house number search" }, "SuggestParBirthLocality": { "type": "object", "properties": { "function": { "type": "string", "enum": ["official", "historical", "all"], "default": "all", "description": "Data set to search: `official`, `historical`, or `all`. Default: `all`" }, "level": { "format": "int32", "type": "number", "description": "Search level: `1` for Country and `5` for City" } }, "description": "Processing parameters for birth locality search" }, "SuggestDataQuery": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "Query string" } }, "description": "Query container holding the input search string" }, "SuggestDataRestrictId": { "allOf": [ { "$ref": "#/components/schemas/SuggestDataQuery" }, { "type": "object", "properties": { "restrict_id": { "format": "int64", "type": "number", "minimum": 1, "description": "ID of the territorial level. Used for filtering the research by a certain territorial level" } } } ], "description": "Territorial search container with parent identifier filter" }, "SuggestDataRestrictIdMandatory": { "allOf": [ { "$ref": "#/components/schemas/SuggestDataQuery" }, { "type": "object", "required": ["restrict_id"], "properties": { "restrict_id": { "format": "int64", "type": "number", "minimum": 1, "description": "ID of the city. Used for filtering the research by a certain territorial level" } } } ], "description": "Search container with mandatory parent territorial identifier" }, "SuggestDataRestrictIdMandatoryHouseNumber": { "allOf": [ { "type": "object", "required": ["restrict_id", "number"], "properties": { "restrict_id": { "format": "int64", "type": "number", "minimum": 1, "description": "ID of the street. Used for filtering the research by a certain street" }, "number": { "format": "int64", "type": "number", "description": "House number" } } } ], "description": "Search container with mandatory street identifier for house number lookup" }, "SuggestDataBirthLocality": { "type": "object", "properties": { "province_code": { "type": "string", "description": "Province code" }, "locality": { "type": "string", "description": "Locality description" }, "locality_id": { "format": "int64", "type": "number", "description": "Locality identifier" }, "belfiore_code": { "type": "string", "description": "Belfiore code" }, "minimum_date": { "type": "string", "description": "Start of validity date (format: YYYY-MM-DD)" }, "maximum_date": { "type": "string", "description": "End of validity date (format: YYYY-MM-DD)" } }, "description": "Search criteria for birth locality lookup" }, "SuggestDataZipCode": { "allOf": [ { "$ref": "#/components/schemas/SuggestDataQuery" }, { "type": "object", "properties": { "zip_level": { "type": "string", "enum": ["L", "S"], "default": "L", "description": "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`" } } } ], "description": "Search criteria for postal code lookup" }, "SuggestDataZipCodeAll": { "type": "object", "properties": { "city_id": { "format": "int64", "type": "number", "description": "ID of the city" }, "street_id": { "format": "int64", "type": "number", "description": "ID of the street" }, "hn": { "format": "int64", "type": "number", "description": "House number" }, "zipcode": { "type": "string", "description": "Postal code" } }, "description": "Search criteria for full postal code lookup" }, "SuggestResponseCountry": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestCountryResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestCountryResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestCountryData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestCountryData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code ISO 3166-1 alpha-3" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" } } }, "SuggestResponseState": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestStateResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestStateResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestStateData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestStateData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code ISO 3166-1 alpha-3" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" } } }, "SuggestResponseRegion": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestRegionResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestRegionResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestRegionData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestRegionData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code ISO 3166-1 alpha-3" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" }, "region": { "type": "string", "description": "Region name" }, "region_code": { "type": "string", "description": "Region code" }, "region_id": { "format": "int64", "type": "number", "description": "ID of the region" } } }, "SuggestResponseProvince": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestProvinceResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestProvinceResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestProvinceData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestProvinceData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code ISO 3166-1 alpha-3" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" }, "region": { "type": "string", "description": "Region name" }, "region_code": { "type": "string", "description": "Region code" }, "region_id": { "format": "int64", "type": "number", "description": "ID of the region" }, "province": { "type": "string", "description": "Province name" }, "province_code": { "type": "string", "description": "Province code" }, "province_id": { "format": "int64", "type": "number", "description": "ID of the province" } } }, "SuggestResponseCity": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestCityResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestCityResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestCityData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestCityData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code ISO 3166-1 alpha-3" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" }, "region": { "type": "string", "description": "Region name" }, "region_code": { "type": "string", "description": "Region code" }, "region_id": { "format": "int64", "type": "number", "description": "ID of the region" }, "province": { "type": "string", "description": "Province name" }, "province_code": { "type": "string", "description": "Province code" }, "province_id": { "format": "int64", "type": "number", "description": "ID of the province" }, "city": { "type": "string", "description": "City name" }, "city_id": { "format": "int64", "type": "number", "description": "ID of the city" }, "zipcode": { "type": "string", "description": "Postal code" } } }, "SuggestResponseDistrict1": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestDistrict1Results", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestDistrict1Results": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestDistrict1Data" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestDistrict1Data": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code ISO 3166-1 alpha-3" }, "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" }, "region": { "type": "string", "description": "Region name" }, "region_code": { "type": "string", "description": "Region code" }, "region_id": { "format": "int64", "type": "number", "description": "ID of the region" }, "province": { "type": "string", "description": "Province name" }, "province_code": { "type": "string", "description": "Province code" }, "province_id": { "format": "int64", "type": "number", "description": "ID of the province" }, "city": { "type": "string", "description": "City name" }, "city_id": { "format": "int64", "type": "number", "description": "ID of the city" }, "district1": { "type": "string", "description": "First-level district name" }, "district1_id": { "format": "int64", "type": "number", "description": "ID of the first-level district" }, "zipcode": { "type": "string", "description": "Postal code" } } }, "SuggestResponseZipCode": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestZipCodeResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestResponseZipCodeAll": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestZipCodeAllResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestZipCodeResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestZipCodeData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestZipCodeAllResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestZipCodeAllData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestZipCodeData": { "type": "object", "properties": { "country": { "type": "string", "description": "Country name" }, "country_id": { "format": "int64", "type": "number", "description": "ID of the country" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" }, "region": { "type": "string", "description": "Region name" }, "region_code": { "type": "string", "description": "Region code" }, "region_id": { "format": "int64", "type": "number", "description": "ID of the region" }, "province": { "type": "string", "description": "Province name" }, "province_code": { "type": "string", "description": "Province code" }, "province_id": { "format": "int64", "type": "number", "description": "ID of the province" }, "city": { "type": "string", "description": "City name" }, "city_id": { "format": "int64", "type": "number", "description": "ID of the city" }, "district1": { "type": "string", "description": "First-level district name" }, "district1_id": { "format": "int64", "type": "number", "description": "ID of the first-level district" }, "street": { "type": "string", "description": "Street name" }, "street_id": { "format": "int64", "type": "number", "description": "ID of the street" }, "number": { "type": "string", "description": "House number" }, "exponent": { "type": "string", "description": "Exponent" }, "zipcode": { "type": "string", "description": "Postal code" }, "building": { "type": "string", "description": "Building name; available only for GBR and IRL" }, "subbuilding": { "type": "string", "description": "Sub-building information; available only for GBR and IRL" }, "organization": { "type": "string", "description": "Organization name; available only for GBR and IRL" } } }, "SuggestZipCodeAllData": { "type": "object", "properties": { "zipcode": { "type": "string", "description": "Postal code" }, "hn_start": { "type": "string", "description": "Range starting house number" }, "hn_end": { "type": "string", "description": "Range ending house number" }, "exp_start": { "type": "string", "description": "Range starting exponent" }, "exp_end": { "type": "string", "description": "Range ending exponent" }, "parity": { "type": "string", "description": "Parity: `E` for even and `O` for odd" }, "range_type": { "type": "string", "description": "Range type: `0` for house number and `2` for kilometer indication" } } }, "SuggestResponseStreet": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestStreetResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestStreetResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestStreetData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestStreetData": { "type": "object", "properties": { "lngout": { "type": "string", "description": "Language code ISO 3166-1 numeric" }, "state": { "type": "string", "description": "State name" }, "state_code": { "type": "string", "description": "State code" }, "state_id": { "format": "int64", "type": "number", "description": "ID of the state" }, "region": { "type": "string", "description": "Region name" }, "region_code": { "type": "string", "description": "Region code" }, "region_id": { "format": "int64", "type": "number", "description": "ID of the region" }, "province": { "type": "string", "description": "Province name" }, "province_code": { "type": "string", "description": "Province code" }, "province_id": { "format": "int64", "type": "number", "description": "ID of the province" }, "city": { "type": "string", "description": "City name" }, "city_id": { "format": "int64", "type": "number", "description": "ID of the city" }, "district1": { "type": "string", "description": "First-level district name" }, "district1_id": { "format": "int64", "type": "number", "description": "ID of the first-level district" }, "zipcode": { "type": "string", "description": "Postal code" }, "street": { "type": "string", "description": "Street name" }, "street_id": { "format": "int64", "type": "number", "description": "ID of the street" } } }, "SuggestResponseHouseNumber": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestHouseNumberResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestResponseBirthLocality": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuggestBirthLocalityResults", "description": "Container object holding suggestion candidate results" }, "system": { "$ref": "#/components/schemas/SuggestSystem", "description": "System error and execution status" } } }, "SuggestBirthLocalityResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestBirthLocalityData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestHouseNumberResults": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestHouseNumberData" }, "description": "Array of candidate matches returned by the suggestion engine" } } }, "SuggestHouseNumberData": { "type": "object", "properties": { "number": { "format": "int64", "type": "number", "description": "House number" }, "exponent": { "type": "string", "description": "Exponent" }, "hn": { "type": "string", "description": "Formatted number" }, "hn_id": { "format": "int64", "type": "number", "description": "ID of the house number" } } }, "SuggestBirthLocalityData": { "type": "object", "properties": { "locality_id": { "format": "int64", "type": "number", "description": "Locality identifier" }, "province_code": { "type": "string", "description": "Province code" }, "locality": { "type": "string", "description": "Locality description" }, "belfiore_code": { "type": "string", "description": "Belfiore code. In case of historical code it will be preceded by S-" }, "minimum_date": { "type": "string", "description": "Start of validity date (format: YYYY-MM-DD)" }, "maximum_date": { "type": "string", "description": "End of validity date (format: YYYY-MM-DD)" } } }, "SuggestSystem": { "type": "object", "properties": { "ret_code": { "format": "int32", "type": "number", "description": "Code: 0 no blocking error, <> 0 blocking error code" }, "des_ret_code": { "type": "string", "description": "Description" } }, "description": "System error and execution status" }, "ValidationRequestJson": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationPar", "description": "Processing options and country context for address validation" }, "data": { "$ref": "#/components/schemas/ValidationDataInput", "description": "Address and customer data fields to validate" } } }, "ValidationPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "geo": { "type": "string", "default": "N", "description": "Activate geocoding.\n\n- `N` No\n- `S` Yes" }, "fmtout": { "type": "string", "description": "Output format.\n\n- `C` Capitalized\n- `M` Upper case\n- `T` Upper case with apostrophes instead of accents\n- `X` Upper case without accents", "default": "C" }, "fmtsht": { "type": "string", "default": "N", "description": "Activate short descriptions.\n\n- `N` No\n- `S` Yes" }, "lngout": { "type": "string", "description": "Output language.\n\n- `NAT` Native output language\n- `TRA` Transliterated output language\n- `INT` International or English output language\n- `` Keep the input language" }, "tpxout": { "type": "string", "description": "Output description format.\n\n- `LAT` Latinized output without accents" }, "hn_code": { "type": "string", "default": "S", "description": "Activate Egon house-number codes." } }, "description": "Processing options and country context for address validation." }, "ValidationDataInput": { "type": "object", "properties": { "phones": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationPhone" }, "description": "Phone numbers to validate" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationEmail" }, "description": "Email addresses to validate" }, "tax_code": { "$ref": "#/components/schemas/ValidationTaxCode", "description": "Tax code input for validation" }, "name": { "$ref": "#/components/schemas/ValidationName", "description": "Name and person demographic fields" }, "address": { "$ref": "#/components/schemas/ValidationAddress", "description": "Address components to normalize and validate" }, "vat_number": { "$ref": "#/components/schemas/ValidationVatNumber", "description": "VAT number input for verification" } }, "description": "Request payload." }, "ValidationPhone": { "type": "object", "properties": { "pre_int": { "type": "string", "description": "International telephone prefix" }, "pre_nat": { "type": "string", "description": "National telephone prefix" }, "number": { "type": "string", "description": "Telephone number" } }, "required": ["number"] }, "ValidationEmail": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address" } }, "required": ["email"] }, "ValidationTaxCode": { "type": "object", "properties": { "cod_iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 country code" }, "cod_type": { "type": "string", "description": "Code type" }, "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationName": { "type": "object", "properties": { "type_ana": { "type": "string", "description": "Name analysis type" }, "gender": { "type": "string", "description": "Gender" }, "full_name": { "type": "string", "description": "Full name" }, "mid_name": { "type": "string", "description": "Middle name" }, "first_name": { "type": "string", "description": "First name" }, "title": { "type": "string", "description": "Title" }, "name_des": { "type": "string", "description": "Name description" }, "birth_date": { "type": "string", "description": "Date of birth" }, "birth_province": { "type": "string", "description": "Province of birth" }, "birth_place": { "type": "string", "description": "Place of birth" } } }, "ValidationAddress": { "type": "object", "properties": { "egoncode_place": { "format": "int64", "type": "number", "description": "Egon place code." }, "egoncode_hn": { "format": "int64", "type": "number", "description": "Egon house-number code." }, "country": { "type": "string", "description": "Country description." }, "state": { "type": "string", "description": "State description." }, "region": { "type": "string", "description": "Region description." }, "province": { "type": "string", "description": "Province description." }, "city": { "type": "string", "description": "City or municipality description." }, "district1": { "type": "string", "description": "First district or locality description." }, "district2": { "type": "string", "description": "Second district or locality description." }, "district3": { "type": "string", "description": "Third district or locality description." }, "zipcode": { "type": "string", "description": "Postal code." }, "street_type": { "type": "string", "description": "Street type, for example Via, Viale, Piazza, or Corso." }, "street": { "type": "string", "description": "Street description or street name." }, "address": { "type": "string", "description": "Full unstructured address." }, "hn": { "type": "string", "description": "House number." }, "care_of": { "type": "string", "description": "Care-of information." }, "building": { "type": "string", "description": "Building information." }, "sub_building": { "type": "string", "description": "Sub-building information." }, "organization": { "type": "string", "description": "Organization name." }, "street_type_str2": { "type": "string", "description": "Second street type." }, "street_2": { "type": "string", "description": "Second street description." }, "hn_2": { "type": "string", "description": "Second house number." } }, "description": "Address information to validate. All individual address fields are optional." }, "ValidationVatNumber": { "type": "object", "properties": { "cod_iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 country code" }, "cod_type": { "type": "string", "description": "Code type" }, "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationResponseJson": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ValidationDataOutput", "description": "Normalized and enriched output data" }, "quality": { "$ref": "#/components/schemas/ValidationQuality", "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationDataOutput": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/ValidationNameData", "description": "Parsed and validated personal or corporate name details" }, "tax_code": { "$ref": "#/components/schemas/ValidationTaxCodeData", "description": "Tax code details" }, "vat_number": { "$ref": "#/components/schemas/ValidationVatNumberData", "description": "VAT number details" }, "address": { "$ref": "#/components/schemas/ValidationAddressData", "description": "Normalized address details" }, "geo": { "$ref": "#/components/schemas/ValidationGeoData", "description": "Geocoding coordinates and source quality level" }, "postal": { "$ref": "#/components/schemas/ValidationPostalData", "description": "Standardized postal output rows" }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationPhoneData" }, "description": "Phone numbers to validate" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationEmailData" }, "description": "Email addresses to validate" }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationCodeData" }, "description": "Administrative and cadastral domain codes" } }, "description": "Normalized address data and optional output." }, "ValidationPhoneData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "type": { "type": "string", "description": "Administrative-code type" }, "pre_int": { "type": "string", "description": "International telephone prefix" }, "pre_nat": { "type": "string", "description": "National telephone prefix" }, "number": { "type": "string", "description": "Telephone number" } } }, "ValidationEmailData": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address" } } }, "ValidationTaxCodeData": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationCodeData": { "type": "object", "properties": { "type": { "type": "string", "description": "Administrative-code type" }, "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationVatNumberData": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationNameData": { "type": "object", "properties": { "type_ana": { "type": "string", "description": "Name analysis type" }, "gender": { "type": "string", "description": "Gender" }, "full_name": { "type": "string", "description": "Full name" }, "last_name": { "type": "string", "description": "Separate surname" }, "mid_name": { "type": "string", "description": "Middle name" }, "first_name": { "type": "string", "description": "First name" }, "prename": { "type": "string", "description": "Separate name" }, "title": { "type": "string", "description": "Title" }, "firm_type": { "type": "string", "description": "Company legal form" }, "birth_date": { "type": "string", "description": "Date of birth" }, "birth_country": { "type": "string", "description": "Country of birth" }, "birth_province": { "type": "string", "description": "Province of birth" }, "birth_place": { "type": "string", "description": "Place of birth" }, "name_des": { "type": "string", "description": "Name description" }, "status": { "type": "string", "description": "Validation status" } } }, "ValidationAddressData": { "type": "object", "properties": { "standard": { "$ref": "#/components/schemas/ValidationStandardData", "description": "Standard postal address formatting" }, "short": { "$ref": "#/components/schemas/ValidationShortData", "description": "Short descriptions" }, "smart": { "$ref": "#/components/schemas/ValidationSmartData", "description": "Smart formatted address components" } }, "description": "Normalized address result." }, "ValidationStandardData": { "type": "object", "properties": { "iso2": { "type": "string", "description": "Country ISO 3166-1 alpha-2 code." }, "iso3": { "type": "string", "description": "Country ISO 3166-1 alpha-3 code." }, "country": { "type": "string", "description": "Normalized country description." }, "country_lng": { "type": "string", "description": "Country language code." }, "state": { "type": "string", "description": "Normalized state description." }, "state_code": { "type": "string", "description": "State code." }, "state_lng": { "type": "string", "description": "State language code." }, "region": { "type": "string", "description": "Normalized region description." }, "region_code": { "type": "string", "description": "Region code." }, "region_lng": { "type": "string", "description": "Region language code." }, "province": { "type": "string", "description": "Normalized province description." }, "province_code": { "type": "string", "description": "Province code." }, "province_lng": { "type": "string", "description": "Province language code." }, "city": { "type": "string", "description": "Normalized city description." }, "city_lng": { "type": "string", "description": "City language code." }, "locality": { "type": "string", "description": "Normalized locality or district description." }, "locality_lng": { "type": "string", "description": "Locality language code." }, "locality2": { "type": "string", "description": "Second locality or district description." }, "locality2_lng": { "type": "string", "description": "Second locality language code." }, "locality3": { "type": "string", "description": "Third locality or district description." }, "locality3_lng": { "type": "string", "description": "Third locality language code." }, "zipcode": { "type": "string", "description": "Normalized postal code." }, "street_type": { "type": "string", "description": "Normalized street-type description." }, "street_name": { "type": "string", "description": "Normalized street name." }, "street": { "type": "string", "description": "Normalized street type and name." }, "street_lng": { "type": "string", "description": "Street language code." }, "address": { "type": "string", "description": "Formatted street address and house number." }, "full_address": { "type": "string", "description": "Complete normalized address." }, "street_type2": { "type": "string", "description": "Second street-type description." }, "street_name2": { "type": "string", "description": "Second street name." }, "street2": { "type": "string", "description": "Second normalized street." }, "street2_lng": { "type": "string", "description": "Second street language code." }, "hn": { "type": "string", "description": "Normalized house number." }, "hn_ext": { "type": "string", "description": "Additional house-number information." }, "care_of": { "type": "string", "description": "Care-of information." }, "hn_2": { "type": "string", "description": "Second house number." }, "building": { "type": "string", "description": "Building information." }, "subbuilding": { "type": "string", "description": "Sub-building information." }, "organization": { "type": "string", "description": "Organization" }, "postal_town1": { "type": "string", "description": "Primary postal town or area." }, "postal_town2": { "type": "string", "description": "Secondary postal town or locality." }, "match_code": { "type": "string", "description": "Address matching result code." }, "adm_code": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationAdmCodeData" }, "description": "Administrative code collection." }, "cnd": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationCndData" }, "description": "Candidate address values when matching is not exact." }, "egon_code": { "$ref": "#/components/schemas/ValidationEgonCodeData", "description": "Egon internal code place, street, and house number" } }, "description": "Complete structured and normalized address." }, "ValidationShortData": { "type": "object", "properties": { "country": { "type": "string", "description": "Country description." }, "state": { "type": "string", "description": "State description." }, "region": { "type": "string", "description": "Region description." }, "province": { "type": "string", "description": "Province description." }, "city": { "type": "string", "description": "City description." }, "locality": { "type": "string", "description": "Locality or district description." }, "locality2": { "type": "string", "description": "Second locality description." }, "locality3": { "type": "string", "description": "Third locality description." }, "street_type": { "type": "string", "description": "Street-type description." }, "street_name": { "type": "string", "description": "Street name." }, "street": { "type": "string", "description": "Street type and name." } }, "description": "Short descriptions, returned when par.fmtsht is enabled." }, "ValidationAdmCodeData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country ISO alpha-3 code." }, "type": { "type": "string", "description": "Administrative-code type." }, "value": { "type": "string", "description": "Administrative code or description." } } }, "ValidationCndData": { "type": "object", "properties": { "province": { "type": "string", "description": "Candidate province." }, "city": { "type": "string", "description": "Candidate city." }, "locality": { "type": "string", "description": "Candidate locality." }, "street": { "type": "string", "description": "Candidate street." }, "zipcode": { "type": "string", "description": "Candidate postal code." }, "street_code": { "format": "int64", "type": "number", "description": "Candidate street code." } } }, "ValidationEgonCodeData": { "type": "object", "properties": { "city": { "format": "int64", "type": "number", "description": "Egon city code." }, "locality": { "format": "int64", "type": "number", "description": "Egon locality code." }, "street": { "format": "int64", "type": "number", "description": "Egon street code." }, "hn": { "format": "int64", "type": "number", "description": "Egon house-number code." } }, "description": "Egon hierarchical code collection." }, "ValidationSmartData": { "type": "object", "properties": { "country": { "type": "string", "description": "Country description" }, "administrative_level": { "type": "string", "description": "Administrative level." }, "city": { "type": "string", "description": "City." }, "address": { "type": "string", "description": "Street type + Street description + House number" }, "zipcode": { "type": "string", "description": "Postal code." } }, "description": "Simplified address representation." }, "ValidationGeoData": { "type": "object", "properties": { "lat_long": { "type": "string", "description": "Coordinates in latitude, longitude format." }, "geo_level": { "type": "string", "description": "Geocoding quality level." }, "census_code": { "type": "string", "description": "Census code." }, "census_lat_long": { "type": "string", "description": "Census coordinates." } }, "description": "Geocoding output, returned when par.geo is set to S." }, "ValidationPostalData": { "type": "object", "properties": { "row1": { "type": "string", "description": "Postal row 1." }, "row2": { "type": "string", "description": "Postal row 2." }, "row3": { "type": "string", "description": "Postal row 3." }, "row4": { "type": "string", "description": "Postal row 4." }, "row5": { "type": "string", "description": "Postal row 5." }, "row6": { "type": "string", "description": "Postal row 6." }, "row7": { "type": "string", "description": "Postal row 7." } }, "description": "Postal-format output rows." }, "ValidationQuality": { "type": "object", "properties": { "phones": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationPhoneQuality" }, "description": "Phone numbers to validate" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationEmailQuality" }, "description": "Email addresses to validate" }, "tax_code": { "$ref": "#/components/schemas/ValidationTaxCodeQuality", "description": "Quality indicator result (see Quality indicators → Tax code section)" }, "name": { "$ref": "#/components/schemas/ValidationNameQuality", "description": "Quality indicator result (see Quality indicators → Person section)" }, "address": { "$ref": "#/components/schemas/ValidationAddressQuality", "description": "Quality indicator result (see Quality indicators → Address section)" }, "vat_number": { "$ref": "#/components/schemas/ValidationVatNumberQuality", "description": "Quality indicator result (see Quality indicators → VAT section)" } }, "description": "Address validation quality indicators." }, "ValidationPhoneQuality": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationEmailQuality": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationTaxCodeQuality": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationVatNumberQuality": { "type": "object", "x-wp-new-istance": true, "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationNameQuality": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationPersonQualityInternal", "description": "Quality indicator result - person" }, "birth_date": { "$ref": "#/components/schemas/ValidationBirthDate", "description": "Quality indicator result - birth date" }, "birth_place": { "$ref": "#/components/schemas/ValidationBirthPlace", "description": "Quality indicator result - birth place" } } }, "ValidationPersonQualityInternal": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationBirthDate": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationBirthPlace": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationAddressQuality": { "type": "object", "properties": { "locality": { "$ref": "#/components/schemas/ValidationLocality", "description": "Quality indicator result - locality" }, "street": { "$ref": "#/components/schemas/ValidationStreet", "description": "Quality indicator result - street" }, "hn": { "$ref": "#/components/schemas/ValidationHouseNumber", "description": "Quality indicator result - house number" } }, "description": "Quality results by address component." }, "ValidationLocality": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag." }, "code": { "format": "int32", "type": "number", "description": "Quality code." }, "description": { "type": "string", "description": "Human-readable quality result." } }, "description": "Quality of locality or city matching." }, "ValidationStreet": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag." }, "code": { "format": "int32", "type": "number", "description": "Quality code." }, "description": { "type": "string", "description": "Human-readable quality result." } }, "description": "Quality of street matching." }, "ValidationHouseNumber": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag." }, "code": { "format": "int32", "type": "number", "description": "Quality code." }, "description": { "type": "string", "description": "Human-readable quality result." } }, "description": "Quality of house-number matching." }, "ValidationSystem": { "type": "object", "properties": { "ret_code": { "format": "int32", "type": "number", "description": "Processing result code. 0 means no blocking error." }, "des_ret_code": { "type": "string", "description": "Human-readable processing result." } }, "description": "Request processing status." }, "ReverseRequestJson": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ReversePar", "description": "Processing parameters for reverse geocoding" }, "data": { "$ref": "#/components/schemas/ReverseDataInput", "description": "Coordinates (latitude, longitude) for reverse geocoding lookup" } } }, "ReversePar": { "type": "object", "required": ["iso3"], "properties": { "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code (ISO 3166-1 alpha-3)" }, "type": { "type": "string", "default": "P", "description": "Type of reverse: `P` punctual or `V` vector" }, "radius": { "format": "int32", "type": "number", "default": 100, "description": "Radius from the input coordinates, in meters" }, "increase_radius": { "format": "int32", "type": "number", "default": 1, "description": "Increased search radius" }, "search_attempts": { "format": "int32", "type": "number", "default": 1, "description": "Number of search attempts" }, "max_candidates": { "format": "int32", "type": "number", "default": 10, "description": "Maximum number of candidates to extract" } } }, "ReverseDataInput": { "type": "object", "required": ["latitude", "longitude"], "properties": { "latitude": { "type": "number", "format": "double", "description": "Latitude" }, "longitude": { "type": "number", "format": "double", "description": "Longitude" } } }, "ReverseResponseJson": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReverseDataOutput", "description": "Matching address candidates for coordinates" }, "system": { "$ref": "#/components/schemas/ReverseSystem", "description": "System error and execution status" } } }, "ReverseDataOutput": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReverseReverseData" }, "description": "Reverse-geocoding results" } } }, "ReverseReverseData": { "type": "object", "properties": { "hn_id": { "format": "int64", "type": "number", "description": "ID of the number" }, "province_code": { "type": "string", "description": "Province code" }, "city": { "type": "string", "description": "City description" }, "locality": { "type": "string", "description": "District description" }, "street": { "type": "string", "description": "Street name" }, "zipcode": { "type": "string", "description": "Postal code" }, "hn": { "type": "string", "description": "House number" }, "exponent": { "type": "string", "description": "Exponent" }, "longitude": { "type": "string", "description": "Longitude" }, "latitude": { "type": "string", "description": "Latitude" }, "distance": { "format": "int64", "type": "number", "description": "Distance (in meters)" } } }, "ReverseSystem": { "type": "object", "properties": { "ret_code": { "format": "int32", "type": "number", "description": "Code: 0 no blocking error, <> 0 blocking error code" }, "des_ret_code": { "type": "string", "description": "Description" } }, "description": "System error and execution status" }, "FullAddressRequestFullAddress": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/FullAddressParFullAddress", "description": "Processing parameters and country context" }, "data": { "$ref": "#/components/schemas/FullAddressDataFullAddress", "description": "Query string and territorial restriction" } } }, "FullAddressParFullAddress": { "type": "object", "required": ["iso3"], "properties": { "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 country code" }, "output": { "type": "string", "description": "Output language. Allowed values: `NAT`, `LAT`, `TRA`, `INT`, or an empty value to keep the input language" } } }, "FullAddressDataFullAddress": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "Free-text query containing the complete address" }, "restrict_id": { "format": "int64", "type": "number", "description": "Identifier of the territorial restriction. Required when `restrict_level` is provided" }, "restrict_level": { "type": "string", "description": "Territorial level used for the restriction. Required when `restrict_id` is provided. Allowed values: `state`, `region`, `province`, `city`, `district1`" } } }, "FullAddressResponseFullAddress": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FullAddressFullAddressResult", "description": "Parsed and normalized candidate addresses" }, "system": { "$ref": "#/components/schemas/FullAddressSystem", "description": "System error and execution status" } } }, "FullAddressFullAddressResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/FullAddressFullAddressData" }, "description": "Array of candidate matching addresses" } } }, "FullAddressFullAddressData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 country code" }, "id": { "format": "int64", "type": "number", "description": "Street identifier" }, "country": { "type": "string", "description": "Country name" }, "state": { "type": "string", "description": "State name" }, "region": { "type": "string", "description": "Region name" }, "province": { "type": "string", "description": "Province name" }, "province_code": { "type": "string", "description": "Province code" }, "city": { "type": "string", "description": "City name" }, "district1": { "type": "string", "description": "First-level district name" }, "district2": { "type": "string", "description": "Second-level district name" }, "district3": { "type": "string", "description": "Third-level district name" }, "zipcode": { "type": "string", "description": "Postal or ZIP code" }, "street": { "type": "string", "description": "Street name" }, "hn_num": { "type": "string", "description": "Numeric portion of the house number" }, "hn_exp": { "type": "string", "description": "House-number suffix or exponent" } } }, "FullAddressSystem": { "type": "object", "properties": { "ret_code": { "format": "int32", "type": "number", "description": "Code: 0 no blocking error, <> 0 blocking error code" }, "des_ret_code": { "type": "string", "description": "Description" } }, "description": "System error and execution status" }, "MapBrokerResponseRoutes": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MapBrokerRoutesData" }, "system": { "$ref": "#/components/schemas/MapBrokerSystem" } } }, "MapBrokerRoutesData": { "type": "object", "description": "Calculated route data.", "properties": { "routes": { "type": "array", "description": "Route(s) calculated.", "items": { "$ref": "#/components/schemas/MapBrokerRoute" } }, "notices": { "type": "array", "description": "Issues related to the route calculation.", "items": { "type": "object" } } } }, "MapBrokerRoute": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique route id." }, "sections": { "type": "array", "description": "Sections composing the route.", "items": { "$ref": "#/components/schemas/MapBrokerSection" } }, "routeLabels": { "type": "array", "description": "Most important names and route numbers.", "items": { "type": "string" } }, "routeHandle": { "type": "string", "description": "Encoded route handle for later route decoding." } } }, "MapBrokerSection": { "type": "object", "properties": { "id": { "type": "string", "description": "Section id." }, "type": { "type": "string", "description": "Section type: `vehicle`, `pedestrian`, or `transit`." }, "departure": { "$ref": "#/components/schemas/MapBrokerWaypoint", "description": "Departure place and time." }, "arrival": { "$ref": "#/components/schemas/MapBrokerWaypoint", "description": "Arrival place and time." }, "summary": { "$ref": "#/components/schemas/MapBrokerSectionSummary", "description": "Section summary." }, "transport": { "$ref": "#/components/schemas/MapBrokerTransport", "description": "Transport information." }, "polyline": { "type": "string", "description": "Route geometry in Flexible Polyline encoding." }, "actions": { "type": "array", "description": "Actions required to complete the section.", "items": { "type": "object" } }, "spans": { "type": "array", "description": "Map content attributes for each span.", "items": { "type": "object" } } } }, "MapBrokerWaypoint": { "type": "object", "properties": { "place": { "$ref": "#/components/schemas/MapBrokerPlace", "description": "Place details." } } }, "MapBrokerPlace": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of place." }, "location": { "$ref": "#/components/schemas/MapBrokerCoordinates", "description": "Actual snapped location coordinates." }, "originalLocation": { "$ref": "#/components/schemas/MapBrokerCoordinates", "description": "Original requested coordinates." } } }, "MapBrokerCoordinates": { "type": "object", "properties": { "lat": { "type": "number", "format": "double", "description": "Latitude (WGS84)." }, "lng": { "type": "number", "format": "double", "description": "Longitude (WGS84)." } } }, "MapBrokerSectionSummary": { "type": "object", "properties": { "duration": { "type": "number", "format": "int64", "description": "Duration in seconds." }, "length": { "type": "number", "format": "int64", "description": "Length in meters." }, "baseDuration": { "type": "number", "format": "int64", "description": "Duration ignoring traffic conditions." } } }, "MapBrokerTransport": { "type": "object", "properties": { "mode": { "type": "string", "description": "Mode of transport used." } } }, "MapBrokerSystem": { "type": "object", "description": "System error status.", "properties": { "ret_code": { "format": "int32", "type": "number", "description": "Code: `0` means no blocking error; a value different from `0` is a blocking error code." }, "des_ret_code": { "type": "string", "description": "Description of the return status." } } }, "ValidationAddressRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationAddressPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["address"], "properties": { "address": { "$ref": "#/components/schemas/ValidationAddress" } }, "description": "Address information to validate" } } }, "ValidationAddressResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ValidationDataOutput", "description": "Normalized and enriched validation output data" }, "quality": { "$ref": "#/components/schemas/ValidationQuality", "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationEmailRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationEmailPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["emails"], "properties": { "emails": { "type": "array", "description": "Email addresses to validate", "items": { "$ref": "#/components/schemas/ValidationEmail" } } }, "description": "Input data to validate" } } }, "ValidationEmailResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "emails": { "type": "array", "description": "Normalized email addresses", "items": { "$ref": "#/components/schemas/ValidationEmail" } } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "emails": { "type": "array", "description": "Quality indicator results for each email", "items": { "$ref": "#/components/schemas/ValidationQualityItem" } } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationNameRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationNamePar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["name"], "properties": { "name": { "$ref": "#/components/schemas/ValidationName", "description": "Personal name components to parse and validate" } }, "description": "Input data to validate" } } }, "ValidationNameResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "type_ana": { "type": "string", "description": "Customer data type" }, "gender": { "type": "string", "description": "Gender" }, "full_name": { "type": "string", "description": "Validated full name" }, "last_name": { "type": "string", "description": "Separate surname" }, "mid_name": { "type": "string", "description": "Middle name" }, "first_name": { "type": "string", "description": "Separate name" }, "prename": { "type": "string", "description": "Name suffix (e.g. Junior/Senior)" }, "title": { "type": "string", "description": "Academic or professional title" }, "firm_type": { "type": "string", "description": "Official juridical specification (e.g. S.R.L., S.P.A.)" }, "birth_date": { "type": "string", "description": "Date of birth in YYYYMMDD format" }, "birth_country": { "type": "string", "description": "Country of birth" }, "birth_province": { "type": "string", "description": "Province of birth" }, "birth_place": { "type": "string", "description": "City of birth" }, "name_des": { "type": "string", "description": "Name designator" }, "status": { "type": "string", "description": "Status" } }, "description": "Parsed, validated, and normalized personal name details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "name": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_date": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_place": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Quality indicators for personal name parsing and demographic verification" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationPhoneRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationPhonePar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["phones"], "properties": { "phones": { "type": "array", "description": "Collection of telephone numbers to validate", "items": { "$ref": "#/components/schemas/ValidationPhone" } } }, "description": "Input data to validate" } } }, "ValidationPhoneResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phones": { "type": "array", "description": "Normalized telephone entries", "items": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "type": { "type": "string", "description": "Telephone-number type code" }, "pre_int": { "type": "string", "description": "Normalized international dialing prefix" }, "pre_nat": { "type": "string", "description": "Normalized national dialing prefix" }, "number": { "type": "string", "description": "Normalized local telephone number" } } } } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "phones": { "type": "array", "description": "Quality result for each returned phone entry", "items": { "$ref": "#/components/schemas/ValidationQualityItem" } } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeCalcRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeCalcPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["name"], "properties": { "name": { "type": "object", "required": [ "full_name", "first_name", "gender", "birth_date", "birth_place" ], "properties": { "full_name": { "type": "string", "description": "Surname" }, "first_name": { "type": "string", "description": "First name" }, "gender": { "type": "string", "description": "Gender (`1` Male, `2` Female)" }, "birth_date": { "type": "string", "description": "Date of birth in `YYYYMMDD` format" }, "birth_place": { "type": "string", "description": "Birth city description" } }, "description": "Identity and demographic data used to calculate tax code" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeCalcResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Calculated Italian tax code" } }, "description": "Calculated Italian tax code details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": { "$ref": "#/components/schemas/ValidationQualityItem" }, "name": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_date": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_place": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Quality indicators for personal name parsing and demographic verification" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeCheckRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeCheckPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["tax_code"], "properties": { "tax_code": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": { "type": "string", "description": "Type of code" }, "cod_description": { "type": "string", "description": "Italian tax code to check" } }, "description": "Italian tax code to validate" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeCheckResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Italian tax code" } }, "description": "Validated tax code details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeExtractRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeExtractPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["tax_code"], "properties": { "tax_code": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": { "type": "string", "description": "Type of code" }, "cod_description": { "type": "string", "description": "Italian tax code to extract info from" } }, "description": "Italian tax code to extract demographics from" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeExtractResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "gender": { "type": "string", "description": "Extracted gender" }, "birth_date": { "type": "string", "description": "Extracted date of birth in `YYYYMMDD` format" }, "birth_province": { "type": "string", "description": "Extracted birth province code" }, "birth_place": { "type": "string", "description": "Extracted birth city description" } }, "description": "Extracted demographic and birthplace data" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeMatchRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeMatchPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["name", "tax_code"], "properties": { "name": { "type": "object", "required": [ "full_name", "first_name", "gender", "birth_date", "birth_place" ], "properties": { "full_name": { "type": "string", "description": "Surname" }, "first_name": { "type": "string", "description": "First name" }, "gender": { "type": "string", "description": "Gender (`1` Male, `2` Female)" }, "birth_date": { "type": "string", "description": "Date of birth in `YYYYMMDD` format" }, "birth_place": { "type": "string", "description": "Birth city description" } }, "description": "Personal identity data to compare against tax code" }, "tax_code": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": { "type": "string", "description": "Code type" }, "cod_description": { "type": "string", "description": "Italian tax code to match" } }, "description": "Italian tax code to match" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeMatchResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "type_ana": { "type": "string", "description": "Person/customer type" }, "gender": { "type": "string", "description": "Normalized gender" }, "full_name": { "type": "string", "description": "Normalized full name" }, "last_name": { "type": "string", "description": "Normalized surname" }, "first_name": { "type": "string", "description": "Normalized first name" }, "birth_date": { "type": "string", "description": "Date of birth in `YYYYMMDD` format" }, "birth_province": { "type": "string", "description": "Birth province code" }, "birth_place": { "type": "string", "description": "Normalized birthplace" } }, "description": "Validated identity data and matching outcome" }, "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Italian tax code result" } }, "description": "Matched tax code details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": { "$ref": "#/components/schemas/ValidationQualityItem" }, "name": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_date": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_place": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Quality indicators for personal name parsing and demographic verification" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationVatCheckRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationVatCheckPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["vat_number"], "properties": { "vat_number": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": { "type": "string", "description": "Type of code" }, "cod_description": { "type": "string", "description": "VAT number to check" } }, "description": "VAT number to formally validate" } }, "description": "Input data to validate" } } }, "ValidationVatCheckResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vat_number": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Validated VAT number" } }, "description": "Formal validation outcome for VAT number" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "vat_number": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationVatExtRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationVatExtPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["vat_number"], "properties": { "vat_number": { "type": "object", "required": ["cod_description"], "properties": { "cod_description": { "type": "string", "description": "VAT number to enrich" } }, "description": "VAT number to query extended company registry for" } }, "description": "Input data to validate" } } }, "ValidationVatExtResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "firm_name": { "type": "string", "description": "Company name" }, "title": { "type": "string", "description": "Company juridical form" }, "status": { "type": "string", "description": "Company operational status" } }, "description": "Company business name and legal form" }, "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Tax code description" } }, "description": "Company fiscal code details" }, "vat_number": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "VAT number" } }, "description": "Extended VAT registration details" }, "address": { "type": "object", "properties": { "standard": { "type": "object", "properties": { "country": { "type": "string", "description": "Country" }, "province": { "type": "string", "description": "Province description" }, "province_code": { "type": "string", "description": "Province abbreviation" }, "city": { "type": "string", "description": "City name" }, "zipcode": { "type": "string", "description": "Postal code" }, "street_type": { "type": "string", "description": "Street type" }, "street_name": { "type": "string", "description": "Street name" }, "full_address": { "type": "string", "description": "Full normalized address" }, "hn": { "type": "string", "description": "House number" } }, "description": "Standardized company registered address details" } }, "description": "Company registered office address details" }, "phones": { "type": "object", "properties": { "type": { "type": "string", "description": "Phone type" }, "number": { "type": "string", "description": "Phone number" } }, "description": "Associated company phone numbers" }, "emails": { "type": "object", "properties": { "type": { "type": "string", "description": "Email type" }, "email": { "type": "string", "description": "Certified email address (PEC)" } }, "description": "Associated company email addresses" }, "codes": { "type": "object", "properties": { "type": { "type": "string", "description": "Code type" }, "cod_description": { "type": "string", "description": "ATECO economic activity code" } }, "description": "Economic activity (Ateco) and registry codes" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "vat_number": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationQualityItem": { "type": "object", "properties": { "flag": { "type": "string", "description": "Quality flag" }, "code": { "type": "number", "description": "Quality result code" }, "description": { "type": "string", "description": "Quality result description" } }, "description": "Quality indicator result (see https://documentation.egon.com/docs/quality-indicators)" }, "ValidationAddressPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "geo": { "type": "string", "default": "N", "description": "Activate geocoding.\n\n- `N` No\n- `S` Yes" }, "fmtout": { "type": "string", "description": "Output format.\n\n- `C` Capitalized\n- `M` Upper case\n- `T` Upper case with apostrophes instead of accents\n- `X` Upper case without accents", "default": "C" }, "fmtsht": { "type": "string", "default": "N", "description": "Activate short descriptions.\n\n- `N` No\n- `S` Yes" }, "lngout": { "type": "string", "description": "Output language.\n\n- `NAT` Native output language\n- `TRA` Transliterated output language\n- `INT` International or English output language\n- `` Keep the input language" }, "tpxout": { "type": "string", "description": "Output description format.\n\n- `LAT` Latinized output without accents" }, "hn_code": { "type": "string", "default": "S", "description": "Activate Egon house-number codes." } }, "description": "Processing options and country context for address validation." }, "ValidationEmailPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for email validation." }, "ValidationNamePar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for name analysis and validation." }, "ValidationPhonePar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for phone number normalization." }, "ValidationTaxCodeCalcPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "3", "description": "Tax-code configuration function.\n\n- `3` Calculate tax code from identity data" } }, "required": ["taxfnx"], "description": "Country context and tax-code calculation function." }, "ValidationTaxCodeCheckPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "2", "description": "Tax-code configuration function.\n\n- `2` Formal check and validation" } }, "required": ["taxfnx"], "description": "Country context and tax-code validation function." }, "ValidationTaxCodeExtractPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "5", "description": "Tax-code configuration function.\n\n- `5` Extract demographic information from tax code" } }, "required": ["taxfnx"], "description": "Country context and tax-code extraction function." }, "ValidationTaxCodeMatchPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "1", "description": "Tax-code configuration function.\n\n- `1` Compare and match tax code against personal identity data" } }, "required": ["taxfnx"], "description": "Country context and tax-code match function." }, "ValidationVatCheckPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for VAT number formal validation." }, "ValidationVatExtPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "vatfnx": { "type": "string", "default": "E", "description": "VAT-number configuration function.\n\n- `E` Extended company registry details lookup" } }, "required": ["vatfnx"], "description": "Country context and extended VAT function." } } } }