{ "openapi": "3.0.3", "info": { "title": "Routing OSM", "version": "1.6", "description": "With the Routing OSM service you can calculate routes from a list of waypoints based on open street map data.", "contact": { "url": "https://developer.myptv.com/" } }, "tags": [ { "name": "Routing" }, { "name": "Reachable Areas" } ], "paths": { "/routes": { "get": { "tags": [ "Routing" ], "description": "Calculates a route by specifying a list of waypoints.", "operationId": "calculateRoute", "parameters": [ { "name": "waypoints", "required": true, "in": "query", "description": "The list of waypoints the route will be calculated for. At least two waypoints are necessary.\nThe first waypoint is the start and the last is the destination of the route.\nAdditional intermediate waypoints are possible. \nThe format of each waypoint is `,[;;;...]`\nrepresenting a point with the latitude value in degrees from south to north\nand the longitude value in degrees (WGS84/EPSG:4326) from west to east.\nThis point will be matched to the nearest possible road. \nBy default the air-line connection between given and matched coordinates is not included in the route polyline, distance and duration.\nWe will refer to this type of waypoint as an _on-road waypoint_.\n\nThe behavior of a waypoint can be changed by appending the following attributes: \n * `includeLastMeters` to include the air-line connection between given and matched coordinates in the route polyline, distance and duration.\n We will refer to this type of waypoint as an _off-road waypoint_.\n * `roadAccess=,`, to use these coordinates for matching to the nearest road. Implies **includeLastMeter**, i.e.\n the air-line connection between the waypoint coordinates and the matched coordinates\n is included in the route polyline, distance and duration. This is useful if the waypoint should not be matched to the nearest possible road but to some road further away,\n e.g. garage exit at a different road.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "49.01318,8.4279;", "49.01835,8.36881;includeLastMeters" ] }, { "$ref": "#/components/parameters/ProfileParameter" }, { "$ref": "#/components/parameters/OptionsParameter" }, { "$ref": "#/components/parameters/ResultsParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteResponse" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reachable-areas": { "get": { "tags": [ "Reachable Areas" ], "description": "Calculates the areas which can be reached from a waypoint, within given horizons (limited to 25 km or 20 minutes). Use the asynchronous POST and GET requests for larger horizons.", "operationId": "calculateReachableAreas", "parameters": [ { "$ref": "#/components/parameters/WaypointParameter" }, { "$ref": "#/components/parameters/ProfileParameter" }, { "$ref": "#/components/parameters/HorizonsParameter" }, { "$ref": "#/components/parameters/HorizonTypeParameter" }, { "$ref": "#/components/parameters/ReachableOptionsParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachableAreas" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Reachable Areas" ], "description": "Starts and creates the areas which can be reached from a waypoint, within given horizons. This type of request is recommended when the `horizons` parameter is more than 20 minutes or 25 km.", "operationId": "startAndCreateReachableAreas", "parameters": [ { "$ref": "#/components/parameters/WaypointParameter" }, { "$ref": "#/components/parameters/ProfileParameter" }, { "$ref": "#/components/parameters/HorizonsParameter" }, { "$ref": "#/components/parameters/HorizonTypeParameter" }, { "$ref": "#/components/parameters/ReachableOptionsParameter" } ], "responses": { "202": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachableAreasId" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reachable-areas/{id}": { "get": { "tags": [ "Reachable Areas" ], "description": "Gets the results of a reachable areas calculation specified by its ID.", "operationId": "getReachableAreas", "parameters": [ { "$ref": "#/components/parameters/ReachableAreasIdParameter" }, { "$ref": "#/components/parameters/MaximumPollingPeriodParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachableAreasResponse" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Reachable Areas" ], "description": "Cancels a reachable areas calculation and deletes the calculated results specified by its ID. Results already calculated cannot be requested by its ID, anymore.", "operationId": "deleteReachableAreas", "parameters": [ { "$ref": "#/components/parameters/ReachableAreasIdParameter" } ], "responses": { "204": { "description": "Response on success." }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "parameters": { "WaypointParameter": { "name": "waypoint", "in": "query", "required": true, "description": "The start or destination waypoint.\nThe format of the waypoint is `,[;;;...]`\nrepresenting a point with the latitude value in degrees from south to north\nand the longitude value in degrees (WGS84/EPSG:4326) from west to east.\nThis point will be matched to the nearest possible road.\nBy default the air-line connection between given and matched coordinates is not included in the distance or duration.\nWe will refer to this type of waypoint as an _on-road waypoint_.\n\nThe behaviour of a waypoint can be changed by appending the following attributes:\n * `includeLastMeters` to include the air-line connection between given and matched coordinates in the distance or duration.\n We will refer to this type of waypoint as an _off-road waypoint_.\n * `roadAccess=,`, to use these coordinates for matching to the nearest road. Implies **includeLastMeters**, i.e.\n the air-line connection between the waypoint coordinates and the matched coordinates\n is included in the distance or duration. This is useful if the waypoint should not be matched to the nearest possible road but to some road further away,\n e.g. garage exit at a different road.\n\nSee [here](./concepts/waypoints) for more information.", "schema": { "type": "string" } }, "ProfileParameter": { "name": "profile", "in": "query", "description": "A profile defines a vehicle by a set of attributes, matching typical transport situations.\nIt must be the name of one of the [predefined profiles](../data-api/concepts/osm-profiles) such as _EUR_OSM_CAR_.", "schema": { "$ref": "#/components/schemas/Profile" } }, "OptionsParameter": { "name": "options", "in": "query", "description": "Routing-relevant options like the polyline format.\nUse array notation like `options[polylineFormat]=GEO_JSON` to set options.", "style": "deepObject", "schema": { "$ref": "#/components/schemas/Options" }, "explode": true }, "ResultsParameter": { "name": "results", "in": "query", "description": "Comma-separated list that defines which results will be returned.\n * `LEGS`\n Response includes information about the route **legs** defined as the parts of the route between two consecutive waypoints.\n * `LEGS_POLYLINE`\n Response includes the **polyline** of each of the **legs** in the format specified by **options[polylineFormat]**. _LEGS_ will automatically be included.\n * `POLYLINE`\n Response includes the complete **polyline** of the entire route in the format specified by **options[polylineFormat]**.", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Results" } }, "example": [ "POLYLINE" ] }, "ReachableOptionsParameter": { "name": "options", "in": "query", "description": "Routing-relevant options like driving direction or the use of additional data.\nUse array notation like `options[drivingDirection]=OUTBOUND` to set options.", "schema": { "$ref": "#/components/schemas/ReachableOptions" }, "explode": true, "style": "deepObject" }, "HorizonsParameter": { "name": "horizons", "in": "query", "description": "The distances [m] or travel times [s] of the horizons, depending on the **horizonType**. Limited to 5 horizons.", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 1 }, "minItems": 1, "maxItems": 5 }, "explode": false }, "HorizonTypeParameter": { "name": "horizonType", "in": "query", "schema": { "$ref": "#/components/schemas/HorizonType" } }, "ReachableAreasIdParameter": { "name": "id", "in": "path", "description": "The ID of a reachable areas calculation.", "required": true, "schema": { "type": "string", "format": "uuid" } }, "MaximumPollingPeriodParameter": { "name": "maximumPollingPeriod", "in": "query", "description": "If the calculation is still running, this operation will be blocked and will not return before this period [ms] expires. If the calculation is completed, it will return immediately.\n\nThe default of 0 ms will cause the operation to return immediately in any case. Use a value > 0 to implement long polling to reduce the number of requests. See the [tutorial](https://developer.myptv.com/en/resources/tutorials/general/how-use-asynchronous-requests-ptv-developer-apis) on asynchronous requests for details.\n", "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0, "maximum": 50000 } } }, "schemas": { "Profile": { "description": "A profile defines a vehicle by a set of attributes, matching typical transport situations.", "type": "string", "default": "EUR_OSM_CAR", "minLength": 1, "maxLength": 50 }, "PolylineFormat": { "type": "string", "description": "Defines the format for polylines in the response.\n * `GEO_JSON` - Polylines are returned in the [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) format.\n * `GOOGLE_ENCODED_POLYLINE` - Polylines are returned in [Google's Encoded Polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) format.", "default": "GEO_JSON", "enum": [ "GEO_JSON", "GOOGLE_ENCODED_POLYLINE" ], "x-enum-varnames": [ "GEO_JSON", "GOOGLE_ENCODED_POLYLINE" ] }, "Options": { "type": "object", "properties": { "polylineFormat": { "$ref": "#/components/schemas/PolylineFormat" } } }, "Results": { "type": "string", "enum": [ "LEGS", "LEGS_POLYLINE", "POLYLINE" ], "x-enum-varnames": [ "LEGS", "LEGS_POLYLINE", "POLYLINE" ] }, "ErrorResponse": { "type": "object", "required": [ "description", "errorCode", "traceId" ], "example": { "traceId": "dc5b4c9a240458dd57128194dfbef0c8", "description": "Invalid or missing authentication credentials.", "errorCode": "GENERAL_UNAUTHENTICATED", "details": { "message": "Invalid API Key." } }, "properties": { "description": { "description": "A human readable message that describes the error.", "type": "string" }, "errorCode": { "description": "A constant string that can be used to identify this error class programmatically.\n\nIf additional information is available for an errorCode, it will be provided as key-value pairs with the parameter **details**. The keys available for a specific errorCode are documented directly with the errorCode. Unless stated otherwise, the values are of type string.\n\nAs an example, the following errorCode provides one key-value pair in the **details**. The key is called **message**.\n* `GENERAL_UNAUTHENTICATED` - Invalid or missing authentication credentials.\n * `message` - An additional error message.\n\nNote that additional errorCodes as well as the **details** of existing errorCodes may be added at any time. Furthermore, the **description** may change at any time.\n\n**HTTP status code: 400**\n* `GENERAL_VALIDATION_ERROR` - The validation of the request failed. Details can be found in **causes**.\n* `GENERAL_PARSING_ERROR` - The JSON syntax is invalid.\n* `ROUTING_ERROR` - The calculation failed. Details can be found in **causes**.\n\n**HTTP status code: 401**\n* `GENERAL_UNAUTHENTICATED` - Invalid or missing authentication credentials.\n * `message` - An additional error message.\n\n**HTTP status code: 403**\n* `GENERAL_FORBIDDEN` - Insufficient access rights.\n* `GENERAL_QUOTA_EXCEEDED` - The transaction limit is exceeded.\n * `message` - An additional error message.\n* `ROUTING_RESTRICTION_EXCEEDED` - A product-specific restriction is exceeded.\n\n**HTTP status code: 404**\n* `GENERAL_RESOURCE_NOT_FOUND` - A requested resource does not exist.\n * `message` - An additional error message.\n\n**HTTP status code: 429**\n* `GENERAL_RATE_LIMIT_EXCEEDED` - The rate limit is exceeded.\n\n**HTTP status code: 500**\n* `GENERAL_INTERNAL_SERVER_ERROR` - The request could not be processed due to an internal error.\n * `message` - An additional error message.\n * `hint` - A hint how to solve the problem.\n\n**HTTP status code: 503**\n* `GENERAL_SERVICE_UNAVAILABLE` - The service is temporarily unavailable.\n\n**HTTP status code: 4xx-5xx**\n* `GENERAL_INTERNAL_GATEWAY_ERROR` - The request could not be processed due to an internal gateway error.\n * `hint` - A hint how to solve the problem.", "type": "string" }, "traceId": { "description": "A unique identifier of the corresponding trace forest. It can be used to trace errors by the support.", "type": "string" }, "errorId": { "description": "A unique identifier specific to this error instance. It can be used to trace errors by the support.", "type": "string" }, "causes": { "description": "A list of affected parameters and/or properties that caused this error.", "type": "array", "items": { "$ref": "#/components/schemas/CausingError" } }, "details": { "description": "Additional properties specific to this error class.", "type": "object", "additionalProperties": true } } }, "CausingError": { "type": "object", "required": [ "description", "errorCode" ], "properties": { "description": { "description": "A human readable message that describes the error.", "type": "string" }, "errorCode": { "description": "A constant string that can be used to identify this error class programmatically.\n\nIf additional information is available for an errorCode, it will be provided as key-value pairs with the parameter **details**. The keys available for a specific errorCode are documented directly with the errorCode. Unless stated otherwise, the values are of type string.\n\nAs an example, the following errorCode provides one key-value pair in the **details**. The key is called **value**.\n* `GENERAL_INVALID_VALUE` - A parameter is set to an invalid value.\n * `value` - The invalid value.\n\nNote that additional errorCodes as well as the **details** of existing errorCodes may be added at any time. Furthermore, the **description** may change at any time.\n\n**Error codes for** `GENERAL_VALIDATION_ERROR`\n\n* `GENERAL_UNRECOGNIZED_PARAMETER` - A parameter is unknown.\n* `GENERAL_MISSING_PARAMETER` - A required parameter is missing.\n* `GENERAL_TYPE_VIOLATED` - The value of a parameter has an invalid type.\n * `type` - The type.\n* `GENERAL_FORMAT_VIOLATED` - The value of a parameter has an invalid format.\n * `format` - The format.\n* `GENERAL_PATTERN_VIOLATED` - The value of a string parameter does not satisfy the required pattern.\n * `pattern` - The pattern.\n* `GENERAL_MINIMUM_LENGTH_VIOLATED` - The minimum length of a string is violated.\n * `minimumLength` - The minimum length (integer).\n* `GENERAL_MAXIMUM_LENGTH_VIOLATED` - The maximum length of a string is violated.\n * `maximumLength` - The maximum length (integer).\n* `GENERAL_MINIMUM_ITEMS_VIOLATED` - The minimum number of items of an array is violated.\n * `minimumItems` - The minimum number of items (integer).\n* `GENERAL_MAXIMUM_ITEMS_VIOLATED` - The maximum number of items of an array is violated.\n * `maximumItems` - The maximum number of items (integer).\n* `GENERAL_MINIMUM_VALUE_VIOLATED` - The minimum value of a parameter is violated.\n * `minimumValue` - The minimum value (integer or double).\n* `GENERAL_MAXIMUM_VALUE_VIOLATED` - The maximum value of a parameter is violated.\n * `maximumValue` - The maximum value (integer or double).\n* `GENERAL_ENUM_VIOLATED` - The value of a parameter is not one of the specified enum values.\n * `enum` - The allowed enum values.\n* `GENERAL_INVALID_VALUE` - A parameter is set to an invalid value.\n * `value` - The invalid value.\n* `GENERAL_DUPLICATE_PARAMETER` - A parameter is duplicated.\n* `GENERAL_INVALID_LIST` - A list has an invalid format such as duplicate commas.\n * `value` - The invalid list.\n* `ROUTING_INVALID_WAYPOINT_ATTRIBUTE` - A waypoint attribute is set to an invalid value.\n * `attribute` - The invalid waypoint attribute.\n* `ROUTING_UNRECOGNIZED_WAYPOINT_ATTRIBUTE` - A waypoint attribute is unknown.\n * `attribute` - The invalid waypoint key.\n* `ROUTING_DUPLICATE_WAYPOINT_ATTRIBUTE` - A waypoint attribute is duplicated.\n * `attribute` - The duplicated waypoint key.\n* `ROUTING_MUST_HAVE_WAYPOINTS` - The request must have at least two waypoints. Deprecated; instead GENERAL_MISSING_PARAMETER is returned.\n* `ROUTING_PROFILE_NOT_FOUND` - The requested profile could not be found.\n * `value` - The profile name.\n* `ROUTING_ESTIMATED_DISTANCE_TOO_LONG` - The distance of the route (estimated by air-line) for non-motorized vehicles is too long. - _The **parameter** remains empty._\n * `distance` - The estimated distance (integer).\n * `limit` - The maximum allowable distance (integer).\n* `ROUTING_MAXIMUM_HORIZON_VALUE_VIOLATED` - The maximum value of horizon is violated.\n * `limit` - The maximum allowable horizon (integer).\n\n**Error codes for** `ROUTING_ERROR`\n\n* `ROUTING_WAYPOINT_CANNOT_BE_MATCHED` - The waypoint cannot be matched to the nearest possible road.\n* `ROUTING_ROUTE_NOT_FOUND` - A route between at least two waypoints could not be found for the current configuration and profile. The **parameter** contains the waypoint where the problematic part that could not be routed starts, i.e., the problematic part of the route is between this waypoint and the next one. Note that only the first problematic part that was encountered is reported.\n\n**Error codes for** `ROUTING_RESTRICTION_EXCEEDED`\n\n* `ROUTING_TOO_MANY_WAYPOINTS` - The request contains too many waypoints.\n * `limit`- The maximum allowed number of waypoints for a single request (integer).\n\n**Error codes for** `GENERAL_RESOURCE_NOT_FOUND`\n\n* `GENERAL_INVALID_ID` - No resource exists for the provided ID.\n * `value` - The ID for which no resource exists.", "type": "string" }, "parameter": { "description": "The name of the affected query or path parameter or a JSONPath to the affected property of the request.", "type": "string" }, "details": { "description": "Additional properties specific to this error class.", "type": "object", "additionalProperties": true } } }, "Leg": { "type": "object", "required": [ "distance", "travelTime" ], "properties": { "distance": { "minimum": 0, "type": "integer", "description": "The distance of the leg [m].", "format": "int32", "example": 1422 }, "travelTime": { "minimum": 0, "type": "integer", "description": "The travel time for the leg [s].", "format": "int32", "example": 56 }, "polyline": { "type": "string", "description": "The polyline of the leg in the format specified by **options[polylineFormat]**." } } }, "Legs": { "type": "array", "description": "The legs of the route.", "items": { "$ref": "#/components/schemas/Leg" } }, "RouteResponse": { "required": [ "distance", "travelTime" ], "type": "object", "properties": { "distance": { "minimum": 0, "type": "integer", "description": "The distance of the route [m].", "format": "int32", "example": 1422 }, "travelTime": { "minimum": 0, "type": "integer", "description": "The travel time for the route [s].", "format": "int32", "example": 56 }, "legs": { "$ref": "#/components/schemas/Legs" }, "polyline": { "description": "The polyline of the route in the format specified by **options[polylineFormat]**.", "type": "string" } } }, "ReachableAreaPolygons": { "type": "array", "items": { "type": "string" }, "description": "The list of polygons calculated for the specified horizons in GeoJson format. For each horizon there is a separate polygon at the same index." }, "ReachableAreasResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/CalculationStatus" }, "reachableAreas": { "$ref": "#/components/schemas/ReachableAreas" }, "error": { "$ref": "#/components/schemas/ErrorResponse" } } }, "ReachableAreas": { "description": "The result of the reachable areas calculation.", "type": "object", "required": [ "polygons" ], "properties": { "polygons": { "$ref": "#/components/schemas/ReachableAreaPolygons" } } }, "DrivingDirection": { "default": "OUTBOUND", "description": "Specifies the driving direction, i.e. from start to destination or from destination to start..\n * `OUTBOUND` - Indicates an outbound routing from start to destination, i.e. the area which can be reached from the location within the given horizon. Use this value to calculate which can be covered e.g. by an emergency service such as a fire department.\n * `INBOUND` - Indicates an inbound routing from destination to start, i.e. from where the location can be reached within the given horizon. Use this value to calculate the catchment area, e.g. of a school or a hospital.", "type": "string", "enum": [ "OUTBOUND", "INBOUND" ], "x-enum-varnames": [ "OUTBOUND", "INBOUND" ] }, "HorizonType": { "default": "TRAVEL_TIME", "description": "Specifies the geographical horizon.\n * `DISTANCE` - Represents a geographical horizon that is described by a distance. Every point or road segment that is reachable from the source within the specified distance is included in the horizon.\n * `TRAVEL_TIME` - Represents a geographical horizon that is described by a travel time. Every point or road segment that is reachable from the source within the specified travel time is included in the horizon.", "type": "string", "enum": [ "DISTANCE", "TRAVEL_TIME" ], "x-enum-varnames": [ "DISTANCE", "TRAVEL_TIME" ] }, "ReachableOptions": { "type": "object", "properties": { "drivingDirection": { "$ref": "#/components/schemas/DrivingDirection" } } }, "CalculationStatus": { "description": "The current status of the calculation.\n * `RUNNING` - The calculation is still running.\n * `SUCCEEDED` - The calculation has completed successfully.\n * `FAILED` - The calculation has completed with a failure.", "type": "string", "enum": [ "RUNNING", "SUCCEEDED", "FAILED" ], "x-enum-varnames": [ "RUNNING", "SUCCEEDED", "FAILED" ] }, "ReachableAreasId": { "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The ID of the calculated reachable areas.", "type": "string", "format": "uuid" } } } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "apiKey" } } }, "security": [ { "apiKeyAuth": [] } ], "servers": [ { "url": "https://api.myptv.com/routing-osm/v1" } ] }