{ "openapi": "3.1.0", "info": { "title": "Egon API - Reverse Geocoding", "version": "1.0.0", "description": "Conversion of geographic coordinates into normalized addresses. Returns the nearest house numbers with street, postal code, and distance." }, "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": "Reverse Geocoding", "description": "Conversion of geographic coordinates into normalized addresses. Returns the nearest house numbers with street, postal code, and distance." } ], "paths": { "/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." } } }, "components": { "securitySchemes": { "tokenAuth": { "type": "apiKey", "in": "header", "name": "token", "description": "Authentication token sent in the `token` request header." } }, "schemas": { "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" } } } }