{ "openapi": "3.1.0", "info": { "title": "Egon API - Suggest Services", "version": "1.0.0", "description": "Predictive autocomplete for countries, cities, streets, postal codes, and house numbers. Results update as you type, so users enter valid addresses." }, "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." } ], "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." } } }, "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" } } } }