{ "openapi": "3.1.0", "info": { "title": "Egon API - Map Broker Services", "version": "1.0.0", "description": "Route calculation and distance matrix services. The Routing endpoint calculates routes for a generic vehicle or for pedestrians." }, "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": "Map Broker Services", "description": "Route calculation and distance matrix services. The Routing endpoint calculates routes for a generic vehicle or for pedestrians." } ], "paths": { "/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": { "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." } } } } } }