{ "openapi": "3.1.0", "info": { "title": "Egon API - Single Line Service", "version": "1.0.0", "description": "Recognition and normalization of a complete address written as a single free-text string. Returns a list of normalized candidates to choose from." }, "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": "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." } ], "paths": { "/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**." } } }, "components": { "securitySchemes": { "tokenAuth": { "type": "apiKey", "in": "header", "name": "token", "description": "Authentication token sent in the `token` request header." } }, "schemas": { "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" } } } }