{
  "openapi": "3.0.1",
  "info": {
    "title": "EWS Road Distance",
    "version": "1.6",
    "description": "With the EWS Road Distance service you can query pre-calculated distances and additional information for relations between reference locations in Europe.",
    "contact": {
      "url": "https://developer.myptv.com/"
    }
  },
  "tags": [
    {
      "name": "Road Distances"
    }
  ],
  "paths": {
    "/relations": {
      "get": {
        "tags": [
          "Road Distances"
        ],
        "description": "Gets the truck distance and additional information for a relation between two locations.",
        "operationId": "getRelation",
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "description": "The start of the relation.",
            "style": "deepObject",
            "schema": {
              "$ref": "#/components/schemas/RequestLocation"
            },
            "explode": true
          },
          {
            "name": "destination",
            "in": "query",
            "description": "The destination of the relation.",
            "style": "deepObject",
            "schema": {
              "$ref": "#/components/schemas/RequestLocation"
            },
            "explode": true
          },
          {
            "name": "region",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/RegionType"
            }
          },
          {
            "name": "dataVersion",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/DataVersionType"
            }
          },
          {
            "name": "results",
            "in": "query",
            "description": "Comma-separated list that defines which results besides the distance will be returned.\n* `COORDINATES`\n    Response includes latitude and longitude of the reference locations of start and destination.\n* `TOLL_DISTANCE`\n    Response includes the distance of toll roads of the relation.",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ResultsType"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Response on success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoadDistanceResponse"
                }
              }
            }
          },
          "default": {
            "description": "Response on failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/suggestions": {
      "get": {
        "tags": [
          "Road Distances"
        ],
        "description": "Gets suggestions for a location. Provide at least two characters in **postalCode** or **locality** to obtain results.",
        "operationId": "getSuggestions",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "The country represented by its code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "postalCode",
            "in": "query",
            "description": "The postal code or its initial characters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locality",
            "in": "query",
            "description": "The name or initial characters of the city or district in the language spoken in that country or region, always transliterated to Latin.\nThe input will first be matched to city names and then to subdistrict names.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/RegionType"
            }
          },
          {
            "name": "dataVersion",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/DataVersionType"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/LocationType"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "description": "Limits the number of results that are returned.",
              "minimum": 1,
              "maximum": 250,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Response on success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestionsResponse"
                }
              }
            }
          },
          "default": {
            "description": "Response on failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "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* `EWS_ERROR` - The relation could not be found.\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\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\n**Error codes for** `EWS_ERROR`\n\n* `EWS_LOCATION_NOT_FOUND` - The location could not be found.\n* `EWS_LOCATION_NOT_UNIQUE` - The location is not unique.\n* `EWS_LOCATION_NOT_SPECIFIED` - The location is not specified.\n* `EWS_TOLL_DISTANCE_NOT_AVAILABLE` - The toll distance is only available for routes with start and destination both in Germany or both in Austria.\n\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
          }
        }
      },
      "RegionType": {
        "type": "string",
        "description": "The region to search for the reference locations. See the concept on [EWS](./concepts/ews) for more information.\n",
        "default": "BEST_QUALITY",
        "enum": [
          "BEST_QUALITY",
          "EUROPE",
          "GERMANY"
        ],
        "x-enum-varnames": [
          "BEST_QUALITY",
          "EUROPE",
          "GERMANY"
        ]
      },
      "DataVersionType": {
        "type": "string",
        "description": "The version of the data by year.\n",
        "default": "LATEST",
        "enum": [
          "V2016",
          "V2017",
          "V2018",
          "V2019",
          "V2020",
          "V2021",
          "V2022",
          "V2023",
          "V2024",
          "V2025",
          "V2026",
          "LATEST"
        ],
        "x-enum-varnames": [
          "V2016",
          "V2017",
          "V2018",
          "V2019",
          "V2020",
          "V2021",
          "V2022",
          "V2023",
          "V2024",
          "V2025",
          "V2026",
          "LATEST"
        ]
      },
      "ResultsType": {
        "type": "string",
        "example": "TOLL_DISTANCE",
        "enum": [
          "COORDINATES",
          "TOLL_DISTANCE"
        ],
        "x-enum-varnames": [
          "COORDINATES",
          "TOLL_DISTANCE"
        ]
      },
      "LocationType": {
        "type": "string",
        "description": "The type of the location.",
        "example": "CITY",
        "default": "CITY",
        "enum": [
          "CITY",
          "PORT",
          "BORDER"
        ],
        "x-enum-varnames": [
          "CITY",
          "PORT",
          "BORDER"
        ]
      },
      "RoadDistanceResponse": {
        "type": "object",
        "required": [
          "distance",
          "start",
          "destination",
          "dataVersion",
          "region"
        ],
        "properties": {
          "distance": {
            "minimum": 0,
            "type": "integer",
            "description": "The distance of the relation [m].",
            "format": "int32",
            "example": 1422
          },
          "tollDistance": {
            "minimum": 0,
            "type": "integer",
            "description": "The distance of toll roads of the relation [m], if requested.",
            "format": "int32",
            "example": 985
          },
          "start": {
            "$ref": "#/components/schemas/ResponseLocation"
          },
          "destination": {
            "$ref": "#/components/schemas/ResponseLocation"
          },
          "dataVersion": {
            "type": "string",
            "description": "The version of the data by year."
          },
          "region": {
            "type": "string",
            "description": "The region which was searched for the reference locations."
          }
        }
      },
      "RequestLocation": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "The country represented by its code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
            "example": "DE"
          },
          "postalCode": {
            "type": "string",
            "description": "The postal code, or zip-code, which is used by a postal authority of a country.",
            "example": "76131"
          },
          "locality": {
            "type": "string",
            "description": "The name of a locality in the language spoken in that country or region, always transliterated to Latin.\nIt can be the name of a city (e.g. 'Karlsruhe'), a subdistrict (e.g. 'Durlach') or a combination of both\nseparated with a blank (e.g. 'Karlsruhe Durlach').",
            "example": "Karlsruhe"
          },
          "type": {
            "$ref": "#/components/schemas/LocationType"
          }
        }
      },
      "ResponseLocation": {
        "type": "object",
        "required": [
          "country",
          "locality",
          "type"
        ],
        "description": "The complete location used for start or destination of the relation.",
        "properties": {
          "country": {
            "type": "string",
            "description": "The country represented by its code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
            "example": "DE"
          },
          "postalCode": {
            "type": "string",
            "description": "The postal code, or zip-code, which is used by a postal authority of a country.",
            "example": "76131"
          },
          "locality": {
            "type": "string",
            "description": "The name of the city or district in the language spoken in that country or region, always transliterated to Latin.",
            "example": "Karlsruhe"
          },
          "latitude": {
            "minimum": -90,
            "maximum": 90,
            "type": "number",
            "description": "The latitude in degrees (WGS84/EPSG:4326) from south to north, if requested.",
            "format": "double",
            "example": 49.013465
          },
          "longitude": {
            "minimum": -180,
            "maximum": 180,
            "type": "number",
            "description": "The longitude in degrees (WGS84/EPSG:4326) from west to east, if requested.",
            "format": "double",
            "example": 8.428155
          },
          "type": {
            "$ref": "#/components/schemas/LocationType"
          }
        }
      },
      "SuggestedLocation": {
        "type": "object",
        "required": [
          "country",
          "locality",
          "type"
        ],
        "description": "A location suggested for the input.",
        "properties": {
          "country": {
            "type": "string",
            "description": "The country represented by its code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
            "example": "DE"
          },
          "postalCode": {
            "type": "string",
            "description": "The postal code, or zip-code, which is used by a postal authority of a country.",
            "example": "76131"
          },
          "locality": {
            "type": "string",
            "description": "The name of the city or district in the language spoken in that country or region, always transliterated to Latin.",
            "example": "Karlsruhe"
          },
          "type": {
            "$ref": "#/components/schemas/LocationType"
          }
        }
      },
      "SuggestionsResponse": {
        "type": "object",
        "properties": {
          "suggestions": {
            "type": "array",
            "description": "The list of suggested locations sorted by **country**, **postalCode** and **locality**.\nInput localities matching a city name will be returned before those matching a subdistrict name.",
            "items": {
              "$ref": "#/components/schemas/SuggestedLocation"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "apiKey"
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://api.myptv.com/ews/v1"
    }
  ]
}