openapi: 3.0.0
servers:
  - url: https://graphhopper.com/api/1
info:
  contact:
    email: support@graphhopper.com
    name: API Support
    url: https://www.graphhopper.com/
  description: |
    
    With the [GraphHopper Directions API](https://www.graphhopper.com/products/) you can integrate A-to-B route planning, turn-by-turn navigation,
    route optimization, isochrone calculations and other tools in your application.

    The GraphHopper Directions API consists of the following RESTful web services:

     * [Routing API](#tag/Routing-API),
     * [Route Optimization API](#tag/Route-Optimization-API),
     * [Isochrone API](#tag/Isochrone-API),
     * [Map Matching API](#tag/Map-Matching-API),
     * [Matrix API](#tag/Matrix-API),
     * [Geocoding API](#tag/Geocoding-API) and
     * [Cluster API](#tag/Cluster-API).

    # Explore our APIs

    ## Get started

    1. [Sign up for GraphHopper](https://support.graphhopper.com/a/solutions/articles/44001976025)
    2. [Create an API key](https://support.graphhopper.com/a/solutions/articles/44001976027)

    Each API part has its own documentation. Jump to the desired API part and learn about the API through the given examples and tutorials.

    In addition, for each API there are specific sample requests that you can send via Insomnia or Postman to see what the requests and responses look like.

    ## Insomnia

    To explore our APIs with [Insomnia](https://insomnia.rest/), follow these steps:

    1. Open Insomnia and Import [our workspace](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/GraphHopper-Direction-API-Insomnia.json).
    2. Specify [your API key](https://graphhopper.com/dashboard/#/register) in your workspace: Manage Environments -> Base Environment -> `"api_key": your API key`
    3. Start exploring

    ![Insomnia](./img/insomnia.png)

    ## Postman

    To explore our APIs with [Postman](https://www.getpostman.com/), follow these steps:

    1. Import our [request collections](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/graphhopper_directions_api.postman_collection.json) as well as our [environment file](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/graphhopper_directions_api.postman_environment.json).
    2. Specify [your API key](https://graphhopper.com/dashboard/#/register) in your environment: `"api_key": your API key`
    3. Start exploring

    ![Postman](./img/postman.png)

    ## API Client Libraries

    To speed up development and make coding easier, we offer the following client libraries:

     * [JavaScript client](https://github.com/graphhopper/directions-api-js-client) - try the [live examples](https://graphhopper.com/api/1/examples/)
     * [Others](https://github.com/graphhopper/directions-api-clients) like C#, Ruby, PHP, Python, ... automatically created for the Route Optimization API

    ### Bandwidth reduction

    If you create your own client, make sure it supports http/2 and gzipped responses for best speed.

    If you use the Matrix, the Route Optimization API or the Cluster API and want to solve large problems, we recommend you to reduce bandwidth
    by [compressing your POST request](https://gist.github.com/karussell/82851e303ea7b3459b2dea01f18949f4)
    and specifying the header as follows: `Content-Encoding: gzip`. This will also avoid the HTTP 413 error "Request Entity Too Large".

    ## Contact Us

    If you have problems or questions, please read the following information:

    - [FAQ](https://graphhopper.com/api/1/docs/FAQ/)
    - [Public forum](https://discuss.graphhopper.com/c/directions-api)
    - [Contact us](https://www.graphhopper.com/contact-form/)
    - [GraphHopper Status Page](https://status.graphhopper.com/)

    To stay informed about the latest developments, you can

    - follow us on [twitter](https://twitter.com/graphhopper/),
    - read [our blog](https://graphhopper.com/blog/),
    - watch [our documentation repository](https://github.com/graphhopper/directions-api-doc),
    - sign up for our newsletter or
    - [our forum](https://discuss.graphhopper.com/c/directions-api).

    Select the channel you like the most.


    # Map Data and Routing Profiles

    Currently, our main data source is [OpenStreetMap](https://www.openstreetmap.org). We also integrated other network data providers.
    This chapter gives an overview about the options you have.

    ## OpenStreetMap

    #### Geographical Coverage

    [OpenStreetMap](https://www.openstreetmap.org) covers the whole world. If you want to see for yourself if we can provide data suitable for your region,
    please visit [GraphHopper Maps](https://graphhopper.com/maps/).
    You can edit and modify OpenStreetMap data if you find that important information is missing, e.g. a weight limit for a bridge.
    [Here](https://wiki.openstreetmap.org/wiki/Beginners%27_guide) is a beginner's guide that shows how to add data. If you have edited data, we usually consider your data after 1 week at the latest.

    #### Supported Vehicle Profiles

    The Routing, Matrix and Route Optimization APIs support the following vehicle profiles:

    Name       | Description           | Restrictions              | Icon
    -----------|:----------------------|:--------------------------|:---------------------------------------------------------
    car        | Car mode              | car access                | ![car image](https://graphhopper.com/maps/img/car.png)
    small_truck| Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.4m, length=5.5m, weight=2080+1400 kg | ![small truck image](https://graphhopper.com/maps/img/small_truck.png)
    truck      | Truck like a MAN or Mercedes-Benz Actros | height=3.7m, width=2.6+0.5m, length=12m, weight=13000 + 13000 kg, hgv=yes, 3 Axes | ![truck image](https://graphhopper.com/maps/img/truck.png)
    scooter    | Moped mode | Fast inner city, often used for food delivery, is able to ignore certain bollards, maximum speed of roughly 50km/h | ![scooter image](https://graphhopper.com/maps/img/scooter.png)
    foot       | Pedestrian or walking without dangerous [SAC-scales](https://wiki.openstreetmap.org/wiki/Key:sac_scale) | foot access         | ![foot image](https://graphhopper.com/maps/img/foot.png)
    hike       | Pedestrian or walking with priority for more beautiful hiking tours and potentially a bit longer than `foot`. Walking duration is influenced by elevation differences.  | foot access         | ![hike image](https://graphhopper.com/maps/img/hike.png)
    bike       | Trekking bike avoiding hills | bike access  | ![bike image](https://graphhopper.com/maps/img/bike.png)
    mtb        | Mountainbike          | bike access         | ![Mountainbike image](https://graphhopper.com/maps/img/mtb.png)
    racingbike| Bike preferring roads | bike access         | ![racingbike image](https://graphhopper.com/maps/img/racingbike.png)

    Please note:

     * all motor vehicles (`car`, `small_truck`, `truck` and `scooter`) support turn restrictions via `turn_costs=true`
     * the free package supports only the vehicle profiles `car`, `bike` or `foot`
     * up to 2 different vehicle profiles can be used in a single optimization request. The number of vehicles is unaffected and depends on your subscription.
     * we offer custom vehicle profiles with different properties, different speed profiles or different access options. To find out more about custom profiles, please [contact us](https://www.graphhopper.com/contact-form/).
     * a sophisticated `motorcycle` profile is available up on request. It is powered by the [Kurviger](https://kurviger.de/en) Routing API and favors curves and slopes while avoiding cities and highways.
     
    ## TomTom

    If you want to include traffic, you can purchase the TomTom Add-on.
    This Add-on only uses TomTom's road network and historical traffic information.
    Live traffic is not yet considered. If you are interested to learn how we consider traffic information, we recommend that you read [this article](https://www.graphhopper.com/blog/2017/11/06/time-dependent-optimization/).

    Please note the following:

     * Currently we only offer this for our [Route Optimization API](#tag/Route-Optimization-API).
     * In addition to our terms, you need to accept TomTom's [End User License Aggreement](https://www.graphhopper.com/tomtom-end-user-license-agreement/).
     * We do *not* use TomTom's web services. We only use their data with our software.
     
    [Contact us](https://www.graphhopper.com/contact-form/) for more details.

    #### Geographical Coverage

    We offer

    - Europe including Russia
    - North, Central and South America
    - Saudi Arabia
    - United Arab Emirates
    - South Africa
    - Australia

    #### Supported Vehicle Profiles

    Name       | Description           | Restrictions              | Icon
    -----------|:----------------------|:--------------------------|:---------------------------------------------------------
    car        | Car mode              | car access                | ![car image](https://graphhopper.com/maps/img/car.png)
    small_truck| Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.4m, length=5.5m, weight=2080+1400 kg | ![small truck image](https://graphhopper.com/maps/img/small_truck.png)
  termsOfService: https://www.graphhopper.com/terms/
  title: GraphHopper Directions API
  version: 1.0.0
  x-apisguru-categories:
    - location
  x-logo:
    altText: GraphHopper
    url: https://twitter.com/graphhopper/profile_image?size=original
  x-origin:
    - format: openapi
      url: https://docs.graphhopper.com/openapi.json
      version: "3.0"
  x-providerName: graphhopper.com
security:
  - api_key: []
tags:
  - description: |
      
      ## Quickstart

      The Route Optimization API can be used to solve [traveling salesman](https://en.wikipedia.org/wiki/Travelling_salesman_problem) or [vehicle routing problems](https://en.wikipedia.org/wiki/Vehicle_routing_problem).
      Solve your first problem by following these steps. If you already have a GraphHopper account, start with step 2.

      1. [Sign up for GraphHopper](https://support.graphhopper.com/a/solutions/articles/44001976025)
      2. [Create an API key](https://support.graphhopper.com/a/solutions/articles/44001976027)
      3. Download [simple traveling salesman problem](https://gist.github.com/oblonski/fb2f2be534c3ebe7bebaa72151194182) and save it in a local folder
      4. Open your command line, go to that local folder and use cURL ([What is cURL?](https://de.wikipedia.org/wiki/CURL)) as follows:

         ```
         curl -X POST -H "Content-Type: application/json"   "https://graphhopper.com/api/1/vrp?key=YOUR_CREATED_API_KEY" --data "@tsp.json"
         ```

      Alternatively, you can use our Editor to explore that API:

      1. Login to your GraphHopper account
      2. Go to **Editor**
      3. Click the **Optimize** button to solve your first problem
      4. Analyze the solution on the **Map** or as raw **JSON Output**

      If you have successfully solved the first problem, we recommend this tutorial - [Getting Started with the Optimization API](https://www.graphhopper.com/blog/2019/05/17/getting-started-with-the-optimization-api-traveling-salesman-problem/).
      It shows and describes the essential elements to model your vehicle routing problem.

      To explore the full specification, we recommend that you either use our [route editor](https://www.graphhopper.com/blog/2015/07/21/graphhoppers-new-route-optimization-editor/),
      which you can find in our [dashboard](https://graphhopper.com/dashboard/),
      or use a REST client such as Insomnia or Postman, as described [here](https://docs.graphhopper.com/#section/Explore-our-APIs/Insomnia).

      ## Tutorials

      We provide [a number of tutorials](https://www.graphhopper.com/tutorial/) illustrating how to use the Route Optimization API and
      how to model your vehicle routing problems:

      - [Getting Start with the Optimization API - Traveling Salesman Problem](https://www.graphhopper.com/blog/2019/05/17/getting-started-with-the-optimization-api-traveling-salesman-problem/)
      - [How to solve a traveling salesman problem with a week-planning horizon?](https://www.graphhopper.com/blog/2020/07/15/how-to-solve-a-traveling-salesman-problem-with-a-week-planning-horizon-and-driver-shifts/)
      - [How to schedule technicians with skills and multiple dependencies between tasks?](https://www.graphhopper.com/blog/2016/06/03/how-to-route-technicians-with-skills-and-multiple-dependencies-between-tasks/)
      - [What is the difference between the min. of completion time and min. transport time?](https://www.graphhopper.com/blog/2016/06/20/what-is-the-difference-between-the-minimization-of-completion-time-and-minimizing-transport-time/)
      - [How to model multiple delivery routes with a single vehicle?](https://www.graphhopper.com/blog/2016/07/21/how-to-model-multiple-delivery-routes-with-a-single-vehicle/)
    name: Route Optimization API
  - description: |
      
      ### Introduction

      ![Routing screenshot](./img/routing-example.png)

      The Routing API is part of the GraphHopper Directions API. Routing is the process of finding the best path connecting
      two or more points, where the meaning of ''best'' depends on the vehicle and use case.

      ### Navigation
      If you plan to use the Routing API for navigation, have a look at our [open source demo navigation application](https://github.com/graphhopper/graphhopper-navigation-example) and adapt it to your needs.

      ### Fast
      To get started using this API, just provide two or more points and retrieve the fastest route through the road
      network that connects them. This type of request is heavily optimized for query performance, so it does not
      allow for some advanced features.
      ### Flexible
      Unlock further flexible features via `ch.disable=true`.
    name: Routing API
  - description: |
      
      ### Introduction

      ![Matrix Example](./img/matrix-example.png)

      The Matrix API is part of the [GraphHopper Directions API](https://graphhopper.com/#directions-api) and with
      it you can calculate many-to-many distances and times a lot more efficient than calling the
      Routing API multiple times.

      In the [Routing API](#tag/Routing-API) we support multiple points, so called 'via points', which results in one
      route being calculated. The Matrix API results in NxM routes, or more precise NxM distances or times being calculated
      but [is a lot faster](https://www.graphhopper.com/blog/2019/06/04/incredibly-fast-distance-matrix-calculations-with-graphhopper/)
      compared to NxM single requests.

      The most simple example is a tourist trying to decide
      which pizza is close to her instead of using beeline distance she can calculate a 1x4 matrix. Or a delivery service
      often in the need of big NxN matrices to solve vehicle routing problems. For example the [GraphHopper Route Optimization API](#tag/Route-Optimization-API)
      uses the Matrix API under the hood to achieve this.

      Some other use cases for the Matrix API:

      * Logistic problems often pick up many items from and deliver them to many locations.
      * Calculating detours with many possible points in-between and selecting the best e.g. interesting for ridesharing or taxi applications. For this 1-to-many requests are necessary.
      * Finding the best tour for a tourist in the need to visit as many points of interests as possible.
      * ...

      ### API Clients and Examples

      See the [clients](#section/API-Clients) section in the main document and [live examples](https://graphhopper.com/api/1/examples/#matrix).

      ### Description

      The Matrix API calculates the well known distance-matrix for a set of points, i.e. it calculates all the distances
      between every point combination. But we do not stop there, we also offer a time-, weight- and route-matrix.
      The weight-matrix can be used as raw input for e.g. a vehicle routing problem ([VRP](http://en.wikipedia.org/wiki/Vehicle_routing_problem))
      and is more precise than a time- or distance-matrix. E.g. for bike routes the actual weight of a route (e.g. the "beauty")
      is what you want to decide if a route is 'better' and not always the taken time or distance.

      A simple illustration for a 3x3 matrix with identical from and to points:

      -          |to_point1|to_point2|to_point3
      :-----------|:--------|:--------|:--------
      from_point1 |0        |1->2     | 1->3
      from_point2 |2->1     |0        | 2->3
      from_point3 |3->1     |3->2     | 0

      A simple illustration for a 1x3 matrix with different start- and end-points:

      -          | to_point1  | to_point2 | t_point3
      :-----------|:-----------|:----------|:--------
      from_pointA |A->1        |A->2       |A->3


      For every route 1->2, 1-3, ... or A->1,A->2,A->3 you can return only the weight, the time and the distance.
      To calculate full routes you can use the [Routing API](#tag/Routing-API).

      ### Limits and Counts

      The cost for one request depends on the number of locations and is documented [here](https://support.graphhopper.com/support/solutions/44000303787#what-is-one-credit).

      One request should not exceed the Matrix API location limit, which depends on the subscription, see the
      pricing tab in our dashboard.
    name: Matrix API
  - description: Everything about geocoding
    name: Geocoding API
  - description: Everything about isochrones
    name: Isochrone API
  - description: Everything about map matching aka "snap to road"
    name: Map Matching API
  - description: |
      
      ### Introduction

      ![Cluster Example](./img/cluster-solution.jpg)

      It solves the “capacity clustering problem” by assigning a set of customers to a given number of distinct groups (called clusters).
      The API “clusters” by minimizing the total distance from each individual customer to its designated group median.
      It can also consider minimum and maximum capacity restrictions for each group.

      Clustering can be used in many practical applications.
      For example, it can help to plan territories, i.e. territory optimization for field teams with large territories for field workers,
      or to solve large vehicle routing problems (VRP).
    name: Cluster API
paths:
  /cluster:
    post:
      description: |
        
        The Cluster endpoint is used with a POST request towards
        `https://graphhopper.com/api/1/cluster?key=<your_key>`. The solution will be provided in the JSON response.
        Please note that for problems that take longer than 10 seconds a bad request error is returned.
        In this case please use the asynchronous [Batch Cluster Endpoint](#operation/asyncClusteringProblem) instead.
      operationId: solveClusteringProblem
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClusterRequest"
        description: Request object that contains the problem to be solved
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClusterResponse"
          description: A response containing the solution
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
          description: Error occurred when reading the request. Request is invalid.
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalErrorMessage"
          description: Error occurred on server side.
      summary: POST Cluster Endpoint
      tags:
        - Cluster API
  /cluster/calculate:
    post:
      description: |
        
        Prefer the [synchronous endpoint](#operation/solveClusteringProblem) and use this Batch Cluster endpoint for
        long running problems only. The work flow is asynchronous:

        - send a POST request towards `https://graphhopper.com/api/1/cluster/calculate?key=<your_key>` and fetch the job_id.
        - poll the solution every 500ms until it gives `status=finished`. Do this with a GET request
          towards `https://graphhopper.com/api/1/cluster/solution/<job_id>?key=<your_key>`.
      operationId: asyncClusteringProblem
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClusterRequest"
        description: Request object that contains the problem to be solved
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobId"
          description: A jobId you can use to retrieve your solution from the server - see solution endpoint.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
          links:
            GetSolutionByJobId:
              description: |
                The `job_id` value returned in the response can be used as the `jobId` parameter in `GET /vrp/{jobId}`.
              operationId: getSolution
              parameters:
                jobId: $response.body#/job_id
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
          description: Error occurred when reading client request. Request is invalid.
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalErrorMessage"
          description: Error occurred on server side.
      summary: Batch Cluster Endpoint
      tags:
        - Cluster API
  "/cluster/solution/{jobId}":
    get:
      description: |
        This endpoint returns the solution of the clustering problems submitted to the [Batch Cluster endpoint](#operation/asyncClusteringProblem).
        You can fetch it with the job_id, you have been sent.
      operationId: getClusterSolution
      parameters:
        - description: Request solution with jobId
          in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClusterResponse"
          description: A response containing the solution
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
          description: Error occurred on client side such as invalid input.
        "404":
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Error message
                    example: Invalid job_id 73314c89-ee4b-459c-aca4-0ad6d6e558da
                    type: string
                  status:
                    default: finished
                    description: status
                    example: finished
                    type: string
                type: object
          description: Requested solution could not be found.
        "500":
          description: Error occurred on server side.
      summary: GET Batch Solution Endpoint
      tags:
        - Cluster API
  /geocode:
    get:
      description: |
        
        ### Introduction

        ![Geocoding Example](./img/geocoding-example.png)

        _Geocoding_ describes the process of transforming an textual address representation to a coordinate (`latitude,longitude`).
        For example the conversion from `Berlin` to `52.5170365,13.3888599`.

        _Reverse geocoding_ converts a coordinate to a textual address representation or place name. Find out more about Geocoding itself on [Wikipedia](http://en.wikipedia.org/wiki/Geocoding).
      operationId: getGeocode
      parameters:
        - description: If you do forward geocoding, this is `required` and is a textual description of the address you are looking for.
          in: query
          name: q
          schema:
            type: string
        - description: Display the search results for the specified locale. Currently French (fr), English (en), German (de) and Italian (it) are supported. If the locale wasn't found the default (en) is used.
          in: query
          name: locale
          schema:
            default: en
            type: string
        - description: Specify the maximum number of results to return
          in: query
          name: limit
          schema:
            default: 10
            format: int32
            type: integer
        - description: It is `required` to be `true` if you want to do a reverse geocoding request. If it is `true`, `point` must be defined as well, and `q` must not be used.
          in: query
          name: reverse
          schema:
            default: false
            type: boolean
        - description: If `true`, the output will be formatted.
          in: query
          name: debug
          schema:
            default: false
            type: boolean
        - description: "_Forward geocoding_: The location bias in the format 'latitude,longitude' e.g. point=45.93272,11.58803. _Reverse geocoding_: The location to find amenities, cities."
          in: query
          name: point
          schema:
            type: string
        - description: |
            The provider parameter is currently under development and can fall back to `default` at any time.
            The intend is to provide alternatives to our default geocoder. Each provider has its own strenghts and might fit better for certain scenarios, so it's worth to compare the different providers.
            To try it append the `provider`parameter to the URL like `&provider=nominatim`,
            the result structure should be identical in all cases - if not, please report this back to us.
            Keep in mind that some providers do not support certain parameters or don't return some fields, for example `osm_id` and `osm_type` are not supported by every geocoding provider.
            If you would like to use additional parameters of one of the providers, but it's not available for the GraphHopper Geocoding API, yet? Please contact us.

            The credit costs can be different for all providers - see [here](https://support.graphhopper.com/support/solutions/articles/44000718211-what-is-one-credit-) for more information about it.

            Currently, only the default provider and gisgraphy supports autocompletion of partial search strings.

            All providers support normal "forward" geocoding and reverse geocoding via `reverse=true`.

            #### Default (`provider=default`)

            This provider returns results of our internal geocoding engine, as described above.
            In addition to the above documented parameters the following parameters are possible:
            * `bbox` - the expected format is `minLon,minLat,maxLon,maxLat`
            * `osm_tag` - you can filter `key:value` or exclude places with certain OpenStreetMap tags `!key:value`. E.g. `osm_tag=tourism:museum` or just the key `osm_tag=tourism`. To exclude multiple tags you add multiple `osm_tag` parameters.

            #### Nominatim (`provider=nominatim`)

            The GraphHopper Directions API uses a commercially hosted Nominatim geocoder. You can try this provider [here](https://nominatim.openstreetmap.org/). The provider does **not** fall under the [restrictions](https://operations.osmfoundation.org/policies/nominatim/) of the Nominatim instance hosted by OpenStreetMap.

            In addition to the above documented parameters Nominatim allows to use the following parameters, which can be used as documented [here](https://github.com/openstreetmap/Nominatim/blob/master/docs/api/Search.md#parameters):

            * `viewbox` - the expected format is `minLon,minLat,maxLon,maxLat`
            * `bounded` - If 1 and a viewbox is given, restrict the result to items contained within that viewbox. Default is 0.

            #### Gisgraphy (`provider=gisgraphy`)

            This provider returns results from the Gisgraphy geocoder which you can try [here](https://services.gisgraphy.com/static/leaflet/index.html).

            **Limitations:** The `locale` parameter is not supported. Gisgraphy does not return OSM tags or an extent.

            Gisgraphy has a special autocomplete API, which you can use by adding `autocomplete=true` (does not work with `reverse=true`). The autocomplete API is optimized on predicting text input, but returns less information.

            In addition to the above documented parameters Gisgraphy allows to use the following parameters, which can be used as documented [here](https://www.gisgraphy.com/documentation/user-guide.php#geocodingservice):

            * `radius` - radius in meters
            * `country` - restrict search for the specified country. The value must be the ISO 3166 Alpha 2 code of the country.

            #### NetToolKit (`provider=nettoolkit`)

            This provider returns results from the NetToolKit provider which is specialized for US addresses and provides a wrapper around Nominatim for other addresses. You can try it [here](https://www.nettoolkit.com/geo/demo).

            The following additional NetToolKit parameters are supported (read [here](https://www.nettoolkit.com/docs/geo/geocoding) for more details):
            - `source`: User can choose which source provider to geocode the address, this value is "NetToolKit" by default
            - `country_code`: an iso-3166-2 country code (e.g : US) filter the results to the specify country code

            **Limitations:** NetToolKit does not support the `locale` parameter. NetToolKit does not return OSM tags (e.g. osm_id, osm_type, osm_value).

            #### OpenCage Data (`provider=opencagedata`)

            This provider returns results from the OpenCageData geocoder which you can try [here](https://geocoder.opencagedata.com/demo).

            In addition to the above documented parameters OpenCage Data allows to use the following parameters, which can be used as documented [here](https://geocoder.opencagedata.com/api#forward-opt):

            * countrycode - The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States. 
            * bounds - the expected format is `minLon,minLat,maxLon,maxLat`
          in: query
          name: provider
          schema:
            default: default
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeocodingResponse"
          description: An array found locations
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected error
      summary: Geocoding Endpoint
      tags:
        - Geocoding API
      x-code-samples:
        - lang: Curl
          source: curl "https://graphhopper.com/api/1/geocode?q=berlin&locale=de&debug=true&key=api_key"
        - lang: Java
          source: |-
            OkHttpClient client = new OkHttpClient();
            Request request = new Request.Builder()
                    .url("https://graphhopper.com/api/1/geocode?q=berlin&locale=de&debug=true&key=api_key")
                    .get()
                    .build();

            Response response = client.newCall(request).execute();
  /isochrone:
    get:
      description: |
        ### Example
        You can get an example response via:

        ```
        curl "https://graphhopper.com/api/1/isochrone?point=51.131108,12.414551&key=[YOUR_KEY]"
        ```

        Don't forget to replace the placeholder with your own key.

        ### Introduction
        ![Isochrone screenshot](./img/isochrone-example.png)

        An isochrone of a location is ''a line connecting points at which a vehicle arrives at the same time'', see Wikipedia.
        With the same API you can also calculate isodistances, just use the parameter distance_limit instead of time_limit`.

        ### Use Cases
        Some possible areas in which this API may be useful to you:

        - real estate analysis
        - realtors
        - vehicle scheduling
        - geomarketing
        - reach of electric vehicles
        - transport planning
        - logistics (distribution and retail network planning)

        ### API Clients and Examples
        See the [clients](#section/API-Clients) section in the main documentation, and [live examples](https://graphhopper.com/api/1/examples/#isochrone).
      operationId: getIsochrone
      parameters:
        - description: Specify the start coordinate
          in: query
          name: point
          required: true
          schema:
            type: string
        - description: Specify which time the vehicle should travel. In seconds.
          in: query
          name: time_limit
          schema:
            default: 600
            format: int32
            type: integer
        - description: Specify which distance the vehicle should travel. In meters.
          in: query
          name: distance_limit
          schema:
            format: int32
            type: integer
        - description: |
            The vehicle profile for which the route should be calculated.
          in: query
          name: vehicle
          schema:
            $ref: "#/components/schemas/VehicleProfileId"
        - description: Number by which to divide the given `time_limit` to create `buckets` nested isochrones of time intervals `time_limit-n*time_limit/buckets`. Applies analogously to `distance_limit`.
          in: query
          name: buckets
          schema:
            default: 1
            format: int32
            type: integer
        - description: |
            If `false` the flow goes from point to the polygon, if `true` the flow goes from the polygon "inside" to the point.
            Example use case for `false`&#58; *How many potential customer can be reached within 30min travel time from your store* vs. `true`&#58; *How many customers can reach your store within 30min travel time.*
          in: query
          name: reverse_flow
          schema:
            default: false
            type: boolean
        - description: Use `"shortest"` to get an isodistance line instead of an isochrone.
          in: query
          name: weighting
          schema:
            default: fastest
            enum:
              - fastest
              - shortest
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IsochroneResponse"
          description: Isochrone Result
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected Error
      summary: Isochrone Endpoint
      tags:
        - Isochrone API
  /match:
    post:
      description: |
        ### Example
        You get an example response for a GPX via:

        ```
        curl -XPOST -H "Content-Type: application/gpx+xml" "https://graphhopper.com/api/1/match?vehicle=car&key=[YOUR_KEY]" --data @/path/to/some.gpx
        ```

        A minimal working GPX file looks like
        ```gpx
        <gpx>
         <trk>
          <trkseg>
           <trkpt lat="51.343657" lon="12.360708"></trkpt>
           <trkpt lat="51.343796" lon="12.361337"></trkpt>
           <trkpt lat="51.342784" lon="12.361882"></trkpt>
          </trkseg>
         </trk>
        </gpx>
        ```

        ### Introduction
        ![Map Matching screenshot](./img/map-matching-example.gif)

        The Map Matching API is part of the GraphHopper Directions API and with this API you can snap measured GPS points typically as GPX files to a digital
        road network to e.g. clean data or attach certain data like elevation or turn instructions to it. Read more at Wikipedia.

        In the example screenshot above and demo you see the Map Matching API in action where the black line is the GPS track and the green one is matched result.

        Most of the times, you can simply POST a GPX file, but some of the request parameters of the [Routing API](#tag/Routing-API) apply here, too.

        ### API Clients and Examples
        See the [clients](#section/API-Clients) section in the main documentation, and [live examples](https://graphhopper.com/api/1/examples/#map-matching).

        ### Limits and Counts
        The cost for one request depends on the number of GPS location and is documented [here](https://graphhopper.com/api/1/docs/FAQ/).

        One request should not exceed the Map Matching API location limit depending on the package, see the pricing in our dashboard.
      operationId: postGPX
      parameters:
        - description: Specify the precision of a point, in meter
          in: query
          name: gps_accuracy
          required: false
          schema:
            type: integer
        - description: Specify the vehicle profile like car
          in: query
          name: vehicle
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteResponse"
          description: Routing Result
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected Error
      summary: Map-match a GPX file
      tags:
        - Map Matching API
  /matrix:
    get:
      description: |
        With this Matrix Endpoint you submit the points and parameters via URL parameters and is the most convenient
        as it works out-of-the-box in the browser. If possible you should
        prefer using the [POST Matrix Endpoint](#operation/postMatrix) that avoids problems with many locations
        and can also gzip the **request**. (Note, that all endpoints return gzipped responses).
      operationId: getMatrix
      parameters:
        - description: Specify multiple points in `latitude,longitude` for which the weight-, route-, time- or distance-matrix should be calculated. In this case the starts are identical to the destinations. If there are N points, then NxN entries will be calculated. The order of the point parameter is important. Specify at least three points. Cannot be used together with from_point or to_point.
          explode: true
          in: query
          name: point
          required: false
          schema:
            items:
              type: string
            type: array
        - description: The starting points for the routes in `latitude,longitude`. E.g. if you want to calculate the three routes A-&gt;1, A-&gt;2, A-&gt;3 then you have one from_point parameter and three to_point parameters.
          explode: true
          in: query
          name: from_point
          required: false
          schema:
            items:
              type: string
            type: array
        - description: The destination points for the routes in `latitude,longitude`.
          explode: true
          in: query
          name: to_point
          required: false
          schema:
            items:
              type: string
            type: array
        - description: Optional parameter. Specifies a hint for each `point` parameter to prefer a certain street for the closest location lookup. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.
          explode: true
          in: query
          name: point_hint
          required: false
          schema:
            items:
              type: string
            type: array
        - description: For the from_point parameter. See point_hint
          explode: true
          in: query
          name: from_point_hint
          required: false
          schema:
            items:
              type: string
            type: array
        - description: For the to_point parameter. See point_hint
          explode: true
          in: query
          name: to_point_hint
          required: false
          schema:
            items:
              type: string
            type: array
        - description: |
            Optional parameter to avoid snapping to a certain road class or road environment. Current supported values `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`. Multiple values are specified like `snap_prevention=ferry&snap_prevention=motorway`
          explode: true
          in: query
          name: snap_prevention
          schema:
            items:
              type: string
            type: array
        - description: Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap.
          explode: true
          in: query
          name: curbside
          required: false
          schema:
            items:
              enum:
                - any
                - right
                - left
              type: string
            type: array
        - description: Curbside setting for the from_point parameter. See curbside.
          explode: true
          in: query
          name: from_curbside
          required: false
          schema:
            items:
              enum:
                - any
                - right
                - left
              type: string
            type: array
        - description: Curbside setting for the to_point parameter. See curbside.
          explode: true
          in: query
          name: to_curbside
          required: false
          schema:
            items:
              enum:
                - any
                - right
                - left
              type: string
            type: array
        - description: Specifies which arrays should be included in the response. Specify one or more of the following options 'weights', 'times', 'distances'. To specify more than one array use e.g. out_array=times&out_array=distances. The units of the entries of distances are meters, of times are seconds and of weights is arbitrary and it can differ for different vehicles or versions of this API.
          explode: true
          in: query
          name: out_array
          required: false
          schema:
            items:
              type: string
            type: array
        - description: The vehicle profile for which the matrix should be calculated.
          in: query
          name: vehicle
          schema:
            $ref: "#/components/schemas/VehicleProfileId"
        - description: Specifies whether or not the matrix calculation should return with an error as soon as possible in case some points cannot be found or some points are not connected. If set to `false` the time/weight/distance matrix will be calculated for all valid points and contain the `null` value for all entries that could not be calculated. The `hint` field of the response will also contain additional information about what went wrong (see its documentation).
          in: query
          name: fail_fast
          required: false
          schema:
            default: true
            type: boolean
        - description: Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
          in: query
          name: turn_costs
          required: false
          schema:
            default: false
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatrixResponse"
          description: Matrix API response
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected Error
      summary: GET Matrix Endpoint
      tags:
        - Matrix API
      x-code-samples:
        - lang: Curl
          source: curl "https://graphhopper.com/api/1/matrix?point=49.932707,11.588051&point=50.241935,10.747375&point=50.118817,11.983337&type=json&vehicle=car&debug=true&out_array=weights&out_array=times&out_array=distances&key=api_key"
        - lang: Java
          source: |-
            OkHttpClient client = new OkHttpClient();
            Request request = new Request.Builder()
                    .url("https://graphhopper.com/api/1/matrix?point=49.932707,11.588051&point=50.241935,10.747375&point=50.118817,11.983337&type=json&vehicle=car&debug=true&out_array=weights&out_array=times&out_array=distances&key=api_key")
                    .get()
                    .build();

            Response response = client.newCall(request).execute();
    post:
      description: |
        
        The [GET endpoint](#operation/getMatrix) has an URL length limitation, which hurts for many locations per request.
        In those cases use this POST endpoint with a JSON as input. The only parameter in the URL will be the key.
        Both request scenarios are identical except that all singular parameter names are named as their plural for a POST request.
        The effected parameters are: `points`, `from_points`, `to_points`, and `out_arrays`. For the remaining parameters
        please refer to the [guide of the GET endpoint](#operation/getMatrix).

        **Please note that in contrast to GET endpoint the points have to be specified as `[longitude, latitude]` array (in that order, similar to [GeoJson](http://geojson.org/geojson-spec.html#examples))**.

        For example the query `point=10,11&point=20,22&vehicle=car` will be converted to the following JSON:
        ```json
        { "points": [[11,10], [22,20]], "vehicle": "car" }
        ```

        A complete curl Example:
        ```bash
        curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix?key=[YOUR_KEY]" -d '{"elevation":false,"out_arrays":["weights", "times"],"from_points":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],"to_points":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],"vehicle":"car"}'
        ```
      operationId: postMatrix
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/MatrixRequest"
                - $ref: "#/components/schemas/SymmetricalMatrixRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatrixResponse"
          description: Matrix API response
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected Error
      summary: POST Matrix Endpoint
      tags:
        - Matrix API
  /matrix/calculate:
    post:
      description: |
        Prefer the [synchronous endpoint](#operation/postMatrix) and use this Batch endpoint for long running problems only.

        The Batch Matrix endpoint allows using matrices with more locations and works asynchronously - similar to the [Batch Route Optimization endpoint](#operation/asyncVRP):
         * Create a HTTP POST request against `/matrix/calculate` and add the key in the URL: `/matrix/calculate?key=[YOUR_KEY]`. This will give you the `job_id` from the response json like `{ "job_id": "7ac65787-fb99-4e02-a832-2c3010c70097" }`
         * Poll via HTTP GET requests every 500ms against `/matrix/solution/[job_id]`

        Here are some full examples via curl:
        ```bash
        $ curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix/calculate?key=[YOUR_KEY]" -d '{"points":[[13.29895,52.48696],[13.370876,52.489575],[13.439026,52.511206]]}'
        {"job_id":"7ac65787-fb99-4e02-a832-2c3010c70097"}
        ```

        Pick the returned `job_id` and use it in the next GET requests:
        ```bash
        $ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"
        {"status":"waiting"}
        ```

        When the calculation is finished (`status:finished`) the JSON response will contain the full matrix JSON under `solution`:
        ```bash
        $ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"
        {"solution":{"weights":[[0.0,470.453,945.414],[503.793,0.0,580.871],[970.49,569.511,0.0]],"info":{"copyrights":["GraphHopper","OpenStreetMap contributors"]}},"status":"finished"}
        ```

        Please note that if an error occured while calculation the JSON will not have a status but contain directly the error message e.g.:
        ```json
        {"message":"Cannot find from_points: 1"}
        ```
        And the optional `hints` array.
      operationId: calculateMatrix
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/MatrixRequest"
                - $ref: "#/components/schemas/SymmetricalMatrixRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobId"
          description: A jobId you can use to retrieve your solution from the server.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected Error
      summary: Batch Matrix Endpoint
      tags:
        - Matrix API
  "/matrix/solution/{jobId}":
    get:
      description: |
        This endpoint returns the solution of a JSON submitted to the Batch Matrix endpoint. You can fetch it with the job_id, you have been sent.
      operationId: getMatrixSolution
      parameters:
        - description: Request solution with jobId
          in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatrixResponse"
          description: A response containing the matrix
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Unexpected Error
      summary: GET Batch Matrix Endpoint
      tags:
        - Matrix API
  /route:
    get:
      description: |
        The GET request is the most simple one: just specify the parameter in the URL and you are done.
        Can be tried directly in every browser.
      operationId: getRoute
      parameters:
        - description: |
            The points for which the route should be calculated. Format: `[latitude,longitude]`. Specify at least an origin and a destination. Via points are possible.
            The maximum number depends on your plan.
          explode: true
          in: query
          name: point
          required: true
          schema:
            items:
              type: string
            type: array
        - description: |
            The `point_hint` is typically a road name to which the associated `point` parameter should be snapped to. Specify no `point_hint` parameter or the same number as you have `point` parameters.
          explode: true
          in: query
          name: point_hint
          schema:
            items:
              type: string
            type: array
        - description: |
            Optional parameter to avoid snapping to a certain road class or road environment. Currently supported values are `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`. Multiple values are specified like `snap_prevention=ferry&snap_prevention=motorway`.
          explode: true
          in: query
          name: snap_prevention
          schema:
            items:
              type: string
            type: array
        - description: |
            The vehicle profile for which the route should be calculated.
          in: query
          name: vehicle
          schema:
            $ref: "#/components/schemas/VehicleProfileId"
        - description: |
            Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap.
          in: query
          name: curbside
          schema:
            items:
              enum:
                - any
                - right
                - left
              type: string
            type: array
        - description: |
            Specifies if turn restrictions should be considered. Enabling this option increases the route computation time. Only supported for motor vehicles and OpenStreetMap.
          in: query
          name: turn_costs
          schema:
            default: false
            type: boolean
        - description: |
            The locale of the resulting turn instructions. E.g. `pt_PT` for Portuguese or `de` for German.
          in: query
          name: locale
          schema:
            default: en
            type: string
        - description: |
            If `true`, a third coordinate, the altitude, is included with all positions in the response.
            This changes the format of the `points` and `snapped_waypoints` fields of the response, in both their
            encodings. Unless you switch off the `points_encoded` parameter, you need special code on the
            client side that can handle three-dimensional coordinates.
            A request can fail if the vehicle profile does not support elevation. See the features object for every vehicle profile.
          in: query
          name: elevation
          schema:
            default: false
            type: boolean
        - description: |
            Optional parameter to retrieve path details. You can request additional details for the route: `street_name`, 
            `time`, `distance`, `max_speed`, `toll`, `road_class`, `road_class_link`, `road_access`, `road_environment`, `lanes`, and `surface`. Read more about the usage of path details [here](https://discuss.graphhopper.com/t/2539).
          explode: true
          in: query
          name: details
          schema:
            items:
              type: string
            type: array
        - description: |
            Normally, the calculated route will visit the points in the order you specified them.
            If you have more than two points, you can set this parameter to `"true"` and the points may be re-ordered to minimize the total travel time.
            Keep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.
          in: query
          name: optimize
          schema:
            default: "false"
            type: string
        - description: |
            If instructions should be calculated and returned
          in: query
          name: instructions
          schema:
            default: true
            type: boolean
        - description: |
            If the points for the route should be calculated at all.
          in: query
          name: calc_points
          schema:
            default: true
            type: boolean
        - description: |
            If `true`, the output will be formatted.
          in: query
          name: debug
          schema:
            default: false
            type: boolean
        - description: |
            Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact
            but requires special client code to unpack. (We provide it in our JavaScript client library!)
            Set this parameter to `false` to switch the encoding to simple coordinate pairs like `[lon,lat]`, or `[lon,lat,elevation]`.
            See the description of the response format for more information.
          in: query
          name: points_encoded
          schema:
            default: true
            type: boolean
        - description: |
            Use this parameter in combination with one or more parameters from below.
          in: query
          name: ch.disable
          schema:
            default: false
            type: boolean
        - description: |
            Determines the way the "best" route is calculated. Besides `fastest` you can use `short_fastest` which finds a reasonable balance between the distance influence (`shortest`) and the time (`fastest`). You could also use `shortest` but is deprecated and not recommended for motor vehicles. All except `fastest` require `ch.disable=true`.
          in: query
          name: weighting
          schema:
            default: fastest
            type: string
        - description: |
            Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.
            In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.
            This parameter also influences the tour generated with `algorithm=round_trip` and forces the initial direction.  Requires `ch.disable=true`.
          explode: true
          in: query
          name: heading
          schema:
            items:
              format: int32
              type: integer
            type: array
        - description: |
            Time penalty in seconds for not obeying a specified heading. Requires `ch.disable=true`.
          in: query
          name: heading_penalty
          schema:
            default: 120
            format: int32
            type: integer
        - description: |
            If `true`, u-turns are avoided at via-points with regard to the `heading_penalty`. Requires `ch.disable=true`.
          in: query
          name: pass_through
          schema:
            default: false
            type: boolean
        - description: |
            Block road access by specifying a point close to the road segment to be blocked, with the format `lat,lon`.
            You can also block all road segments crossing a geometric shape. Specify a circle using the format `lat,lon,radius`, or a polygon using the format `lat1,lon1,lat2,lon2,...,latN,lonN`.
            You can specify several shapes, separating them with `;`. Requires `ch.disable=true`.
          in: query
          name: block_area
          schema:
            type: string
        - description: |
            Specify which road classes and environments you would like to avoid. 
            Possible values are `motorway`, `steps`, `track`, `toll`, `ferry`, `tunnel` and `bridge`.
            Separate several values with `;`. Obviously not all the values make sense for all vehicle profiles e.g. `bike` is already forbidden on a `motorway`. Requires `ch.disable=true`.
          in: query
          name: avoid
          schema:
            type: string
        - description: |
            Rather than looking for the shortest or fastest path, this parameter lets you solve two different problems related to routing:
            With `alternative_route`, we give you not one but several routes that are close to optimal, but
            not too similar to each other. 
            With `round_trip`, the route will get you back to where you started. This is meant for fun (think of
            a bike trip), so we will add some randomness. The `round_trip` option requires `ch.disable=true`.
            You can control both of these features with additional parameters, see below. 
          in: query
          name: algorithm
          schema:
            enum:
              - round_trip
              - alternative_route
            type: string
        - description: |
            If `algorithm=round_trip`, this parameter configures approximative length of the resulting round trip. Requires `ch.disable=true`.
          in: query
          name: round_trip.distance
          schema:
            default: 10000
            format: int32
            type: integer
        - description: |
            If `algorithm=round_trip`, this sets the random seed. Change this to get a different tour for each value.
          in: query
          name: round_trip.seed
          schema:
            format: int64
            type: integer
        - description: |
            If `algorithm=alternative_route`, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.
          in: query
          name: alternative_route.max_paths
          schema:
            default: 2
            format: int32
            type: integer
        - description: |
            If `algorithm=alternative_route`, this parameter sets the factor by which the alternatives routes can be longer than the optimal route. Increasing can lead to worse alternatives.
          in: query
          name: alternative_route.max_weight_factor
          schema:
            default: 1.4
            type: number
        - description: |
            If `algorithm=alternative_route`, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.
          in: query
          name: alternative_route.max_share_factor
          schema:
            default: 0.6
            type: number
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteResponse"
          description: Routing Result
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Your request is not valid. For example, you specified too few or too many points.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Authentication necessary
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: API limit reached.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Internal server error. We get notified automatically and fix this asap.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "501":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Only a special list of vehicles is supported.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
      summary: GET Route Endpoint
      tags:
        - Routing API
      x-code-samples:
        - lang: Curl
          source: curl "https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,3.867&vehicle=car&locale=de&calc_points=false&key=api_key"
        - lang: Java
          source: |-
            OkHttpClient client = new OkHttpClient();
            Request request = new Request.Builder()
                    .url("https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,3.867&vehicle=car&locale=de&calc_points=false&key=api_key")
                    .get()
                    .build();

            Response response = client.newCall(request).execute();
    post:
      description: |
        Please see the [GET endpoint](#operation/getRoute) for a simpler method on how to get started.
        If you are familiar with POST requests and JSON then do not hesitate to continue here.

        Especially when you use many locations you should get familiar with this POST endpoint as the GET endpoint
        has an URL length limitation. Additionally the request of this POST endpoint can be compressed and can slightly
        speed up the request.

        To do a request you send JSON data. Both request scenarios GET and POST are identical except that all singular parameter names are named as their plural for a POST request.
        The effected parameters are: `points`, `point_hints` and `snap_preventions`.

        **Please note that in opposite to the GET endpoint, points are specified in the order of `longitude, latitude`**.

        For example `point=10,11&point=20,22` will be converted to the `points` array (plural):
        ```json
        { "points": [[11,10], [22,20]] }
        ```
        Note again that also the order changes from `[latitude,longitude]` to `[longitude,latitude]`
        similar to [GeoJson](http://geojson.org/geojson-spec.html#examples).

        Example:
        ```bash
        curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/route?key=[YOUR_KEY]" -d '{"elevation":false,"points":[[-0.087891,51.534377],[-0.090637,51.467697]],"vehicle":"car"}'
        ```
      operationId: postRoute
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RouteRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteResponse"
          description: Routing Result
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Your request is not valid. For example, you specified too few or too many points.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Authentication necessary
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: API limit reached.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Internal server error. We get notified automatically and fix this asap.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "501":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GHError"
          description: Only a special list of vehicles is supported.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
      summary: POST Route Endpoint
      tags:
        - Routing API
  /route/info:
    get:
      description: |
        Use this to find out details about the supported vehicle profiles and features, or if you just need to ping the server.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
          description: Coverage Information
      summary: Coverage information
      tags:
        - Routing API
  /vrp:
    post:
      description: |
        
        To get started with the Route Optimization API, please read the [introduction](#tag/Route-Optimization-API).

        To solve a new vehicle routing problem, make a HTTP POST to this URL

        ```
        https://graphhopper.com/api/1/vrp?key=<your_key>
        ```

        It returns the solution to this problem in the JSON response.

        Please note that this URL is very well suited to solve minor problems.
        Larger vehicle routing problems, which take longer than 10 seconds to solve, cannot be solved.
        To solve them, please use the [batch mode URL](#operation/asyncVRP) instead.
      operationId: solveVRP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Request"
        description: The request that contains the vehicle routing problem to be solved.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
          description: A response containing the solution
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
          description: Error occurred when reading the request. Request is invalid.
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalErrorMessage"
          description: Error occurred on server side.
      summary: POST route optimization problem
      tags:
        - Route Optimization API
      x-code-samples:
        - lang: Curl
          source: |-
            curl -X POST -H "Content-Type: application/json"   "https://graphhopper.com/api/1/vrp?key=api_key"   -d '{
              "vehicles": [
                {
                  "vehicle_id": "my_vehicle",
                  "start_address": {
                    "location_id": "berlin",
                    "lon": 13.406,
                    "lat": 52.537
                  }
                }
              ],
              "services": [
                {
                  "id": "hamburg",
                  "name": "visit_hamburg",
                  "address": {
                    "location_id": "hamburg",
                    "lon": 9.999,
                    "lat": 53.552
                  }
                },
                { 
                 "id": "munich",
                  "name": "visit_munich",
                  "address": {
                    "location_id": "munich",
                    "lon": 11.57,
                    "lat": 48.145
                  }
                }
              ]}'
        - lang: Java
          source: |-
            OkHttpClient client = new OkHttpClient();
            MediaType mediaType = MediaType.parse("application/json");
            RequestBody body = RequestBody.create(mediaType, "{\n  \"vehicles\": [\n    {\n      \"vehicle_id\": \"my_vehicle\",\n      \"start_address\": {\n        \"location_id\": \"berlin\",\n        \"lon\": 13.406,\n        \"lat\": 52.537\n      }\n    }\n  ],\n  \"services\": [\n    {\n      \"id\": \"hamburg\",\n      \"name\": \"visit_hamburg\",\n      \"address\": {\n        \"location_id\": \"hamburg\",\n        \"lon\": 9.999,\n        \"lat\": 53.552\n      }\n    },\n    { \n     \"id\": \"munich\",\n      \"name\": \"visit_munich\",\n      \"address\": {\n        \"location_id\": \"munich\",\n        \"lon\": 11.57,\n        \"lat\": 48.145\n      }\n    }\n  ]}");
            Request request = new Request.Builder()
                    .url("https://graphhopper.com/api/1/vrp?key=api_key")
                    .post(body)
                    .addHeader("content-type", "application/json")
                    .build();

            Response response = client.newCall(request).execute();
  /vrp/optimize:
    post:
      description: |
        
        To solve a vehicle routing problem, perform the following steps:

        1.) Make a HTTP POST to this URL

        ```
        https://graphhopper.com/api/1/vrp/optimize?key=<your_key>
        ```

        It returns a job id (job_id).

        2.) Take the job id and fetch the solution for the vehicle routing problem from this URL:

        ```
        https://graphhopper.com/api/1/vrp/solution/<job_id>?key=<your_key>
        ```

        We recommend to query the solution every 500ms until it returns 'status=finished'.

        **Note**: Since the workflow is a bit more cumbersome and since you lose some time in fetching the solution, you should always prefer
        the [synchronous endpoint](#operation/solveVRP). You should use the batch mode only for long running problems.
      operationId: asyncVRP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Request"
        description: The request that contains the problem to be solved.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobId"
          description: A jobId you can use to retrieve your solution from the server - see solution endpoint.
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
          links:
            GetSolutionByJobId:
              description: |
                The `job_id` value returned in the response can be used as the `jobId` parameter in `GET /vrp/{jobId}`.
              operationId: getSolution
              parameters:
                jobId: $response.body#/job_id
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
          description: Error occurred when reading client request. Request is invalid.
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalErrorMessage"
          description: Error occurred on server side.
      summary: POST route optimization problem (batch mode)
      tags:
        - Route Optimization API
      x-code-samples:
        - lang: Curl
          source: |-
            curl -X POST -H "Content-Type: application/json"   "https://graphhopper.com/api/1/vrp/optimize?key=api_key"   -d '{
              "vehicles": [
                {
                  "vehicle_id": "my_vehicle",
                  "start_address": {
                    "location_id": "berlin",
                    "lon": 13.406,
                    "lat": 52.537
                  }
                }
              ],
              "services": [
                {
                  "id": "hamburg",
                  "name": "visit_hamburg",
                  "address": {
                    "location_id": "hamburg",
                    "lon": 9.999,
                    "lat": 53.552
                  }
                },
                { 
                 "id": "munich",
                  "name": "visit_munich",
                  "address": {
                    "location_id": "munich",
                    "lon": 11.57,
                    "lat": 48.145
                  }
                }
              ]}'
        - lang: Java
          source: |-
            OkHttpClient client = new OkHttpClient();
            MediaType mediaType = MediaType.parse("application/json");
            RequestBody body = RequestBody.create(mediaType, "{\n  \"vehicles\": [\n    {\n      \"vehicle_id\": \"my_vehicle\",\n      \"start_address\": {\n        \"location_id\": \"berlin\",\n        \"lon\": 13.406,\n        \"lat\": 52.537\n      }\n    }\n  ],\n  \"services\": [\n    {\n      \"id\": \"hamburg\",\n      \"name\": \"visit_hamburg\",\n      \"address\": {\n        \"location_id\": \"hamburg\",\n        \"lon\": 9.999,\n        \"lat\": 53.552\n      }\n    },\n    { \n     \"id\": \"munich\",\n      \"name\": \"visit_munich\",\n      \"address\": {\n        \"location_id\": \"munich\",\n        \"lon\": 11.57,\n        \"lat\": 48.145\n      }\n    }\n  ]}");
            Request request = new Request.Builder()
                    .url("https://graphhopper.com/api/1/vrp/optimize?key=api_key")
                    .post(body)
                    .addHeader("content-type", "application/json")
                    .build();

            Response response = client.newCall(request).execute();
  "/vrp/solution/{jobId}":
    get:
      description: |
        
        Take the job id and fetch the solution for the vehicle routing problem from this URL:

        ```
        https://graphhopper.com/api/1/vrp/solution/<job_id>?key=<your_key>
        ```

        You get the job id by sending a vehicle routing problem to the [batch mode URL](#operation/asyncVRP).
      operationId: getSolution
      parameters:
        - description: Request solution with jobId
          in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
          description: A response containing the solution
          headers:
            X-RateLimit-Credits:
              description: The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Your current daily credit limit.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Your remaining credits until the reset.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: The number of seconds that you have to wait before a reset of the credit count is done.
              schema:
                type: integer
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
          description: Error occurred on client side such as invalid input.
        "404":
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Error message
                    example: Invalid job_id 73314c89-ee4b-459c-aca4-0ad6d6e558da
                    type: string
                  status:
                    default: finished
                    description: status
                    example: finished
                    type: string
                type: object
          description: Requested solution could not be found.
        "500":
          description: Error occurred on server side.
      summary: GET the solution (batch mode)
      tags:
        - Route Optimization API
      x-code-samples:
        - lang: Curl
          source: curl -X GET "https://graphhopper.com/api/1/vrp/solution/job_id?key=api_key"
        - lang: Java
          source: |-
            OkHttpClient client = new OkHttpClient();
            Request request = new Request.Builder()
                    .url("https://graphhopper.com/api/1/vrp/solution/job_id?key=api_key")
                    .get()
                    .build();

            Response response = client.newCall(request).execute();
components:
  schemas:
    Activity:
      properties:
        address:
          $ref: "#/components/schemas/ResponseAddress"
        arr_date_time:
          description: Arrival date time with offset like this 1970-01-01T01:00+01:00. If you do not use time-dependent optimization, this is `null`.
          format: date-time
          type: string
        arr_time:
          description: Arrival time at this activity in seconds. If type is `start`, this is not available (since it makes no sense to have `arr_time` at start). However, `end_time` is available and actually means \"departure time\" at start location. It is important to note that `arr_time` does not necessarily mean \"start of underlying activity\", it solely means arrival time at activity location. If this activity has no time windows and if there are no further preparation times, `arr_time` is equal to activity start time.
          format: int64
          type: integer
        distance:
          description: cumulated distance from start to this activity in m
          format: int64
          type: integer
        driving_time:
          description: cumulated driving time from start to this driver activity in seconds
          format: int64
          type: integer
        end_date_time:
          description: End date time with offset like this 1970-01-01T01:00+01:00. If you do not use time-dependent optimization, this is `null`.
          format: date-time
          type: string
        end_time:
          description: End time of and thus departure time at this activity. If type is `end`, this is not available (since it makes no sense to have an `end_time` at end) `end_time` at each activity is equal to the departure time at the activity location.
          format: int64
          type: integer
        id:
          description: Id referring to the underlying service or shipment, i.e. the shipment or service this activity belongs to
          type: string
        load_after:
          description: Array with size/capacity dimensions after this activity
          items:
            description: dimension value
            format: int32
            type: integer
          type: array
        load_before:
          description: Array with size/capacity dimensions before this activity
          items:
            description: dimension value
            format: int32
            type: integer
          type: array
        location_id:
          description: Id that refers to address
          type: string
        preparation_time:
          description: preparation time at this activity in seconds
          format: int64
          type: integer
        type:
          description: type of activity
          enum:
            - start
            - end
            - service
            - pickupShipment
            - deliverShipment
            - pickup
            - delivery
            - break
          type: string
        waiting_time:
          description: Waiting time at this activity in seconds. A waiting time can occur if the activity has at least one time window. If `arr_time` < `time_window.earliest` a waiting time of `time_window_earliest` - `arr_time` occurs.
          format: int64
          type: integer
      type: object
    Address:
      properties:
        curbside:
          default: any
          description: Optional parameter. Specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. Only supported for motor vehicles and OpenStreetMap.
          enum:
            - right
            - left
            - any
          example: If you would like to arrive at this address without having to cross the street use `curbside=right/left` for countries with right/left-hand driving. Using `curbside=any` is the same as not specifying this parameter at all.
          type: string
        lat:
          description: Latitude of location.
          example: 51.512665
          format: double
          type: number
        location_id:
          description: Specifies the id of the location.
          example: 550e8400-e29b-11d4-a716-446655440000
          type: string
        lon:
          description: Longitude of location.
          example: -0.092869
          format: double
          type: number
        name:
          description: Name of location.
          example: Queens Victoria Street 70, Second Floor, Flat 245
          type: string
        street_hint:
          description: Optional parameter. Specifies a hint for each address to better snap the coordinates (lon,lat) to road network. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.
          example: Queens Victoria Street 70
          type: string
      required:
        - location_id
        - lon
        - lat
      type: object
    Algorithm:
      deprecated: true
      description: Use `objectives` instead.
      properties:
        objective:
          enum:
            - transport_time
            - completion_time
          type: string
        problem_type:
          enum:
            - min
            - min-max
          type: string
      type: object
    BadRequest:
      properties:
        hints:
          description: Optional error information.
          items:
            $ref: "#/components/schemas/ErrorMessage"
          type: array
        message:
          description: Short error message
          example: Bad Request
          type: string
        status:
          default: finished
          description: status
          example: finished
          type: string
      type: object
    Cluster:
      properties:
        ids:
          description: Array of customer ids assigned to this specific cluster
          example:
            - GraphHopper GmbH
          items:
            type: string
          type: array
        quantity:
          description: Cluster size
          example: 40
          format: int32
          type: number
      type: object
    ClusterConfiguration:
      properties:
        clustering:
          $ref: "#/components/schemas/ClusterConfigurationClustering"
        response_type:
          default: json
          description: Specifies the response format. You can either choose `geojson` or `json`.
          example: json
          type: string
        routing:
          $ref: "#/components/schemas/ClusterConfigurationRouting"
      type: object
    ClusterConfigurationClustering:
      properties:
        max_quantity:
          description: Specifies max. quantity in a cluster
          example: 50
          format: int32
          type: number
        min_quantity:
          description: Specifies min. quantity in a cluster
          example: 30
          format: int32
          type: number
        num_clusters:
          description: Specifies the number of clusters
          example: 10
          format: int32
          type: number
      type: object
    ClusterConfigurationRouting:
      properties:
        cost_per_meter:
          description: Cost per meter (travel distance)
          example: 0
          format: double
          type: number
        cost_per_second:
          description: Cost per second (travel time)
          example: 1
          format: double
          type: number
        profile:
          description: The routing profile for which the travel times and distances should be calculated. Other profiles are listed [here](#section/Map-Data-and-Routing-Profiles/OpenStreetMap)
          example: car
          type: string
      type: object
    ClusterCustomer:
      properties:
        address:
          $ref: "#/components/schemas/ClusterCustomerAddress"
        id:
          description: id of customer
          example: GraphHopper GmbH
          type: string
        quantity:
          description: demand of customer
          example: 10
          format: int32
          type: number
      type: object
    ClusterCustomerAddress:
      properties:
        lat:
          description: Latitude
          example: 48.118434
          format: double
          type: number
        lon:
          description: Longitude
          example: 11.53941
          format: double
          type: number
        street_hint:
          description: Optional parameter. Specifies a hint for each address to better snap the coordinates (lon,lat) to road network. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.
          example: Lindenschmitstraße 52
          type: string
      type: object
    ClusterRequest:
      properties:
        configuration:
          $ref: "#/components/schemas/ClusterConfiguration"
        customers:
          items:
            $ref: "#/components/schemas/ClusterCustomer"
          type: array
      type: object
    ClusterResponse:
      properties:
        clusters:
          items:
            $ref: "#/components/schemas/Cluster"
          type: array
        copyrights:
          example:
            - GraphHopper
            - OpenStreetMap contributors
          items:
            type: string
          type: array
        processing_time:
          example: 4900
          format: double
          type: number
        status:
          description: Indicates the current status of the job
          enum:
            - waiting_in_queue
            - processing
            - finished
          example: finished
          type: string
        waiting_time_in_queue:
          format: double
          type: number
      type: object
    Configuration:
      description: Specifies general configurations that are taken into account when solving the vehicle routing problem.
      properties:
        routing:
          $ref: "#/components/schemas/Routing"
      type: object
    CostMatrix:
      properties:
        data:
          description: JSON data of matrix response
          properties:
            distances:
              items:
                items:
                  format: double
                  type: number
                type: array
              minItems: 1
              type: array
            info:
              description: Additional information for your request
              properties:
                copyrights:
                  items:
                    type: string
                  type: array
                took:
                  format: double
                  type: number
              type: object
            times:
              items:
                items:
                  format: int64
                  type: integer
                type: array
              minItems: 1
              type: array
          type: object
        location_ids:
          items:
            type: string
          type: array
        profile:
          description: vehicle profile or empty if catch all fallback
          type: string
        type:
          description: type of cost matrix, currently default or google are supported
          enum:
            - default
            - google
          type: string
      type: object
    Detail:
      properties:
        code:
          description: |
            Reason code

            Code   |  Reason
            :------|:---------
            1 | cannot serve required skill
            2 | cannot be visited within time window
            3 | does not fit into any vehicle due to capacity
            4 | cannot be assigned due to max distance constraint of vehicles
            21 | could not be assigned due to relation constraint
            22 | could not be assigned due to allowed vehicle constraint
            23 | could not be assigned due to max-time-in-vehicle constraint
            24 | driver does not need a break
            25 | could not be assigned due to disallowed vehicle constraint
            26 | could not be assigned due to max drive time constraint
            27 | could not be assigned due to max job constraint
            28 | could not be assigned due to max activity constraint
            50 | underlying location cannot be accessed over road network by at least one vehicle
          format: int32
          type: integer
        id:
          description: Id of unassigned service/shipment
          type: string
        reason:
          description: Human readable reason as listed above
          type: string
      type: object
    DriveTimeBreak:
      properties:
        duration:
          description: Specifies the duration of the break in seconds.
          example: 2700
          format: int64
          type: integer
        initial_driving_time:
          description: Specifies the initial (current) driving time of a driver to allow dynamic adaptations in seconds.
          example: 3600
          format: int64
          type: integer
        max_driving_time:
          description: Specifies the max driving time (in a row) without break in seconds.
          example: 14400
          format: int64
          type: integer
        possible_split:
          description: Array specifying how a break duration (in seconds) can be split into several smaller breaks
          example:
            - 900
            - 1800
          items:
            format: int64
            type: integer
          type: array
      required:
        - duration
        - max_driving_time
      type: object
    EncodedLineString:
      description: A polyline-encoded list of positions. You'll need to decode this string in client code. We provide open source code in [Java](https://github.com/graphhopper/graphhopper/blob/e649aaed8d3f4378bf2d8889bbbc2318261eabb2/web-api/src/main/java/com/graphhopper/http/WebHelper.java#L54) and [JavaScript](https://github.com/graphhopper/directions-api-js-client/blob/cf43d1a5bc93a3e8007a44fcfc551117e4fa49bc/src/GHUtil.js#L27).
      type: string
    ErrorMessage:
      properties:
        details:
          description: Details
          example: class java.lang.IllegalArgumentException
          type: string
        message:
          description: error message
          example: "unsupported json property [vehiles]. allowed properties: [vehicles, vehicle_types, services, shipments, relations, algorithm, objectives, cost_matrices, configuration]"
          type: string
      type: object
    GHError:
      properties:
        hints:
          description: Optional error information.
          items:
            properties:
              message:
                type: string
            type: object
          type: array
        message:
          type: string
      type: object
    GeocodingLocation:
      properties:
        city:
          description: The city of the address
          type: string
        country:
          description: The country of the address
          type: string
        housenumber:
          description: The housenumber of the address
          type: string
        name:
          description: The name of the entity. Can be a boundary, POI, address, etc
          type: string
        osm_id:
          description: The OSM ID of the entity
          type: string
        osm_key:
          description: The OSM key of the entity
          type: string
        osm_type:
          description: N = node, R = relation, W = way
          type: string
        point:
          $ref: "#/components/schemas/GeocodingPoint"
        postcode:
          description: The postcode of the address
          type: string
        state:
          description: The state of the address
          type: string
        street:
          description: The street of the address
          type: string
      type: object
    GeocodingPoint:
      properties:
        lat:
          description: Latitude
          format: double
          type: number
        lng:
          description: Longitude
          format: double
          type: number
      type: object
    GeocodingResponse:
      example:
        hits:
          - city: Berlin
            country: Deutschland
            name: Berlin
            osm_id: 240109189
            osm_key: place
            osm_type: N
            osm_value: city
            point:
              lat: 52.5170365
              lng: 13.3888599
            postcode: "10117"
          - country: Deutschland
            extent:
              - 13.088345
              - 52.6755087
              - 13.7611609
              - 52.33826
            name: Berlin
            osm_id: 62422
            osm_key: place
            osm_type: R
            osm_value: city
            point:
              lat: 52.5198535
              lng: 13.4385964
          - city: Berlin
            country: Deutschland
            extent:
              - 13.3906703
              - 52.5200704
              - 13.3948873
              - 52.5175007
            name: Humboldt-Universität zu Berlin
            osm_id: 120456814
            osm_key: amenity
            osm_type: W
            osm_value: university
            point:
              lat: 52.51875685
              lng: 13.393560493637775
            postcode: "10117"
            street: Dorotheenstraße
          - city: Berlin
            country: Deutschland
            extent:
              - 13.3924346
              - 52.5191829
              - 13.3948768
              - 52.517526
            housenumber: "6"
            name: Humboldt-Universität zu Berlin
            osm_id: 6647
            osm_key: building
            osm_type: R
            osm_value: yes
            point:
              lat: 52.51840935
              lng: 13.392908021752554
            postcode: "10117"
            street: Unter den Linden
          - city: Berlin
            country: Deutschland
            extent:
              - 13.2364563
              - 52.5161915
              - 13.2433375
              - 52.5129557
            housenumber: "3"
            name: Olympiastadion Berlin
            osm_id: 38862723
            osm_key: leisure
            osm_type: W
            osm_value: stadium
            point:
              lat: 52.5147077
              lng: 13.239776301622072
            postcode: "14053"
            street: Olympischer Platz
          - city: Berlin
            country: Deutschland
            extent:
              - 13.3739245
              - 52.528547
              - 13.3818019
              - 52.5229778
            name: Charité Universitätsmedizin Berlin
            osm_id: 583306346
            osm_key: amenity
            osm_type: W
            osm_value: hospital
            point:
              lat: 52.52585125
              lng: 13.377739577932736
            postcode: "10117"
            street: Hufelandweg
          - city: Berlin
            country: Deutschland
            extent:
              - 13.3906159
              - 52.5190301
              - 13.3923847
              - 52.5174089
            housenumber: "8"
            name: Staatsbibliothek zu Berlin
            osm_id: 180594
            osm_key: amenity
            osm_type: R
            osm_value: library
            point:
              lat: 52.5182233
              lng: 13.391516532100738
            postcode: "10117"
            street: Unter den Linden
          - city: Berlin
            country: Deutschland
            name: Berlin Hauptbahnhof
            osm_id: 3856100103
            osm_key: railway
            osm_type: N
            osm_value: station
            point:
              lat: 52.5249451
              lng: 13.3696614
            postcode: "10557"
            street: Washingtonplatz
          - city: Berlin
            country: Deutschland
            name: Schlacht um Berlin
            osm_id: 1078631331
            osm_key: historic
            osm_type: N
            osm_value: battlefield
            point:
              lat: 52.5127537
              lng: 13.3814231
            postcode: "10117"
            street: Gertrud-Kolmar-Straße
          - city: Berlin
            country: Deutschland
            extent:
              - 13.3807495
              - 52.5083344
              - 13.3822459
              - 52.5074359
            housenumber: "5"
            name: Abgeordnetenhaus von Berlin
            osm_id: 1154556
            osm_key: office
            osm_type: R
            osm_value: government
            point:
              lat: 52.50786655
              lng: 13.381504320489928
            postcode: "10117"
            street: Niederkirchnerstraße
        took: 37
      properties:
        hits:
          items:
            $ref: "#/components/schemas/GeocodingLocation"
          type: array
        took:
          description: in ms
          format: int64
          type: number
    GroupRelation:
      properties:
        groups:
          description: An array of groups that should be related
          example:
            - group-A
            - group-B
          items:
            description: group of services or shipments
            type: string
          type: array
        type:
          description: |
            Specifies the type of relation. It must be either of type `in_sequence` or `in_direct_sequence`.
          example: in_direct_sequence
          type: string
      required:
        - type
        - groups
      type: object
    InfoResponse:
      description: Information about the server and the geographical area that it covers.
      example:
        bbox:
          - 13.072624
          - 52.333508
          - 13.763972
          - 52.679616
        build_date: 2014-02-21T16:52
        features:
          car:
            elevation: false
          foot:
            elevation: true
        version: "0.4"
      properties:
        bbox:
          description: |
            The bounding box of the geographical area covered by this GraphHopper instance. Format: `"minLon,minLat,maxLon,maxLat"
          type: string
        features:
          description: |
            The supported features, such as elevation, per vehicle profile.
          type: object
        version:
          description: |
            The version of the GraphHopper server that provided this response. This is not related to the API version.
          type: string
      type: object
    InternalErrorMessage:
      properties:
        code:
          default: 500
          example: 500
          format: int32
          type: integer
        message:
          description: Details
          example: There has been an internal server error.
          type: string
      type: object
    IsochroneResponse:
      example:
        polygons:
          - geometry:
              coordinates:
                - - 13.351851
                  - 52.51345
                - - 13.350402
                  - 52.516949
                - - 13.352598
                  - 52.522252
                - - 13.351851
                  - 52.51345
              type: Polygon
            properties:
              bucket: 0
            type: Feature
      properties:
        copyrights:
          items:
            type: string
          type: array
        polygons:
          description: |
            The list of polygons in GeoJson format. It can be used e.g. in the Leaflet framework:

            ```
            L.geoJson(json.polygons).addTo(map)
            ```

            The number of polygon is identical to the specified buckets in the query. Every polygon contains the bucket number in the properties section of the GeoJson.
          items:
            $ref: "#/components/schemas/IsochroneResponsePolygon"
          type: array
      type: object
    IsochroneResponsePolygon:
      description: A found path
      properties:
        geometry:
          $ref: "#/components/schemas/Polygon"
        properties:
          properties:
            bucket:
              format: int32
              type: integer
          type: object
        type:
          type: string
      type: object
    JobId:
      properties:
        job_id:
          description: UUID. Unique id for your job/request with which you can fetch your solution
          example: 44886560-b584-4da5-b245-768151dacd8f
          format: uuid
          type: string
      type: object
    JobRelation:
      properties:
        ids:
          description: Specifies an array of shipment and/or service ids that are in relation. If you deal with services then you need to use the id of your services in ids. To also consider sequences of the pickups and deliveries of your shipments, you need to use a special ID, i.e. use your shipment id plus the keyword `_pickup` or `_delivery`. If you want to place a service or shipment activity at the beginning of your route, use the special ID `start`. In turn, use `end` to place it at the end of the route.
          example:
            - pickup-1
            - pickup-2
          items:
            type: string
          type: array
        type:
          description: |+
            Specifies the type of relation. It must be either of type `in_same_route`, `in_sequence` or `in_direct_sequence`.

            `in_same_route`: As the name suggest, it enforces the specified services or shipments to be in the same route. It can be specified as follows:

            ```json
            {
               "type": "in_same_route",
               "ids": ["serv_i_id","serv_j_id"]
            }
            ```

            This enforces service i to be in the same route as service j no matter which vehicle will be employed. If a specific vehicle (driver) is required to conduct this, just add a `vehicle_id` like this:

            ```
            {
               "type": "in_same_route",
               "ids": ["serv_i_id","serv_j_id"],
               "vehicle_id": "vehicle1"
            }
            ```

            This not only enforce service i and j to be in the same route, but also makes sure that both services are in the route of `vehicle1`.

            *Tip*: This way initial loads and vehicle routes can be modelled. For example, if your vehicles are already on the road and new orders come in, then vehicles can still be rescheduled subject to the orders that have already been assigned to these vehicles.



            `in_sequence`: This relation type enforces n jobs to be in sequence. It can be specified as

            ```json
            {
               "type": "in_sequence",
               "ids": ["serv_i_id","serv_j_id"]
            }
            ```

            which means that service j need to be in the same route as service i AND it needs to occur somewhere after service i. As described above if a specific vehicle needs to conduct this, just add `vehicle_id`.


            `in_direct_sequence`: This enforces n services or shipments to be in direct sequence. It can be specified as

            ```json
            {
               "type": "in_direct_sequence",
               "ids": ["serv_i_id","serv_j_id","serv_k_id"]
            }
            ```

            yielding service j to occur directly after service i, and service k to occur directly after service j i.e. in strong order. Again, a vehicle can be assigned a priority by adding a `vehicle_id` to the relation.


            *Special IDs*:
            If you look at the previous example and you want service i to be the first in the route, use the special ID `start` as follows:

            ```json
            {
               "type": "in_direct_sequence",
               "ids": ["start","serv_i_id","serv_j_id","serv_k_id"]
            }
            ```

            Latter enforces the direct sequence of i, j and k at the beginning of the route. If this sequence should be bound to the end of the route, use the special ID `end` like this:

            ```json
            {
               "type": "in_direct_sequence",
               "ids": ["serv_i_id","service_j_id","serv_k_id","end"]
            }
            ```

            If you deal with services then you need to use the 'id' of your services in the field 'ids'. To also consider sequences of the pickups and deliveries of your shipments, you need to use a special ID, i.e. use the shipment id plus the keyword `_pickup` or `_delivery`. For example, to ensure that the pickup and delivery of the shipment with the id 'my_shipment' are direct neighbors, you need the following specification:

            ```
            {
               "type": "in_direct_sequence",
               "ids": ["my_ship_pickup","my_ship_delivery"]
            }
            ```

          example: in_direct_sequence
          type: string
        vehicle_id:
          description: Id of pre-assigned vehicle, i.e. the vehicle id that is determined to conduct the services and shipments in this relation.
          example: driver-Peter
          type: string
      required:
        - type
        - ids
      type: object
    LineString:
      properties:
        coordinates:
          description: |
            A list of coordinate pairs or triples, `[lon,lat]` or `[lon,lat,elevation]`.
          items:
            items:
              type: number
            type: array
          type: array
        type:
          type: string
      type: object
    MatrixRequest:
      example:
        from_point_hints:
          - Copenhagen Street
          - Richmond Avenue
          - White Lion Street
        from_points:
          - - -0.11379003524780275
            - 51.53664617804063
          - - -0.10866165161132814
            - 51.538621486960956
          - - -0.11059284210205078
            - 51.53245503603458
        out_arrays:
          - weights
          - times
          - distances
        to_point_hints:
          - Cannon
          - Cornhill
        to_points:
          - - -0.09576559066772462
            - 51.512882367963456
          - - -0.08797645568847656
            - 51.51317615367198
        vehicle: car
      properties:
        fail_fast:
          default: true
          description: Specifies whether or not the matrix calculation should return with an error as soon as possible in case some points cannot be found or some points are not connected. If set to `false` the time/weight/distance matrix will be calculated for all valid points and contain the `null` value for all entries that could not be calculated. The `hint` field of the response will also contain additional information about what went wrong (see its documentation).
          type: boolean
        from_curbsides:
          description: See `curbsides`of symmetrical matrix
          items:
            type: string
          type: array
        from_point_hints:
          description: See `point_hints`of symmetrical matrix
          items:
            type: string
          type: array
        from_points:
          description: The starting points for the routes in an array of `[longitude,latitude]`. For instance, if you want to calculate three routes from point A such as A->1, A->2, A->3 then you have one `from_point` parameter and three `to_point` parameters.
          items:
            items:
              format: double
              type: number
            type: array
          type: array
        out_arrays:
          description: Specifies which matrices should be included in the response. Specify one or more of the following options `weights`, `times`, `distances`. The units of the entries of `distances` are meters, of `times` are seconds and of `weights` is arbitrary and it can differ for different vehicles or versions of this API.
          items:
            type: string
          type: array
        snap_preventions:
          description: See `snap_preventions` of symmetrical matrix
          items:
            type: string
          type: array
        to_curbsides:
          description: See `curbsides`of symmetrical matrix
          items:
            type: string
          type: array
        to_point_hints:
          description: See `point_hints`of symmetrical matrix
          items:
            type: string
          type: array
        to_points:
          description: The destination points for the routes in an array of `[longitude,latitude]`.
          items:
            items:
              format: double
              type: number
            type: array
          type: array
        turn_costs:
          default: false
          description: Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
          type: boolean
        vehicle:
          allOf:
            - $ref: "#/components/schemas/VehicleProfileId"
            - description: The vehicle profile for which the route should be calculated. Other vehicles are listed [here](#section/Map-Data-and-Routing-Profiles/OpenStreetMap) for the details.
      type: object
    MatrixResponse:
      example:
        distances:
          - - 0
            - 97653
            - 48887
          - - 97426
            - 0
            - 121035
          - - 49006
            - 121049
            - 0
        info:
          copyrights:
            - GraphHopper
            - OpenStreetMap contributors
        times:
          - - 0
            - 4197
            - 2994
          - - 4192
            - 0
            - 6074
          - - 3006
            - 6062
            - 0
        weights:
          - - 0
            - 5662.551
            - 3727.147
          - - 5653.807
            - 0
            - 7889.653
          - - 3741.528
            - 7878.365
            - 0
      properties:
        distances:
          description: The distance matrix for the specified points in the same order as the time matrix. The distances are in meters. If `fail_fast=false` the matrix will contain `null` for connections that could not be found.
          items:
            items:
              format: int64
              type: number
            type: array
          type: array
        hints:
          description: Optional. Additional response data.
          items:
            properties:
              details:
                description: Details of this hint
                type: string
              invalid_from_points:
                description: Optional. An array of from_point indices of points that could not be found. Will only be added if `fail_fast=false` and some `from_point`s were not found.`
                items:
                  format: int32
                  type: number
                type: array
              invalid_to_points:
                description: Optional. An array of to_point indices of points that could not be found. Will only be added if `fail_fast=false` and some `to_point`s were not found.`
                items:
                  format: int32
                  type: number
                type: array
              message:
                description: Short description of this hint
                type: string
              point_pairs:
                description: Optional. An array of two-element arrays representing the from/to_point indices of points for which no connection could be found. Will only be added if `fail_fast=false` and some connections were not found.
                items:
                  items:
                    format: int32
                    type: number
                  type: array
                type: array
            type: object
          type: array
        info:
          $ref: "#/components/schemas/ResponseInfo"
        times:
          description: The time matrix for the specified points in the order [[from1->to1, from1->to2, ...], [from2->to1, from2->to2, ...], ...]. The times are in seconds. If `fail_fast=false` the matrix will contain `null` for connections that could not be found.
          items:
            items:
              format: int64
              type: number
            type: array
          type: array
        weights:
          description: The weight matrix for the specified points in the same order as the time matrix. The weights for different vehicles can have a different unit but the weights array is perfectly suited as input for Vehicle Routing Problems as it is currently faster to calculate. If `fail_fast=false` the matrix will contain `null` for connections that could not be found.
          items:
            items:
              format: double
              type: number
            type: array
          type: array
      type: object
    Objective:
      example:
        type: min
        value: vehicles
      properties:
        type:
          default: min
          description: |
            Type of objective function, i.e. `min` or `min-max`.

             * `min`: Minimizes the objective value.
             * `min-max`: Minimizes the maximum objective value.

            For instance, `min` -> `vehicles` minimizes the number of employed vehicles.
            `min` -> `completion_time` minimizes the sum of your vehicle routes' completion time.

            If you use, for example, `min-max` -> `completion_time`, it minimizes the maximum of your vehicle routes' completion time, i.e. it minimizes the overall makespan.
            This only makes sense if you have more than one vehicle. In case of one vehicle, switching from `min` to `min-max` should not have any impact.
            If you have more than one vehicle, then the algorithm tries to constantly move stops from one vehicle to another such that
            the completion time of longest vehicle route can be further reduced. For example, if you have one vehicle that takes 8 hours
            to serve all customers, adding another vehicle (and using `min-max`) might halve the time to serve all customers to 4 hours. However,
            this usually comes with higher transport costs.

            If you want to minimize `vehicles` first and, second, `completion_time`, you can also combine different objectives like this:

            ```json
            "objectives" : [
               {
                  "type": "min",
                  "value": "vehicles"
               },
               {
                  "type": "min",
                  "value": "completion_time"
               }
            ]
            ```

            If you want to balance activities or the number of stops among all employed drivers, you need to specify it as follows:

            ```json
            "objectives" : [
               {
                  "type": "min-max",
                  "value": "completion_time"
               },
               {
                  "type": "min-max",
                  "value": "activities"
               }
            ]
            ```
          enum:
            - min
            - min-max
          type: string
        value:
          default: transport_time
          description: |
            The value of the objective function.
            The objective value `transport_time` solely considers the time
            your drivers spend on the road, i.e. transport time. In contrary to `transport_time`, `completion_time` also takes waiting times at customer sites into account.
            The `completion_time` of a route is defined as the time from starting to ending the route,
            i.e. the route's transport time, the sum of waiting times plus the sum of activity durations.
            Note that choosing `transport_time` or `completion_time` only makes a difference if you specified time windows for your services/shipments since only in
            scenarios with time windows waiting times can occur.
            The objective value `vehicles` can only be used along with `min` and minimizes vehicles.
          enum:
            - completion_time
            - transport_time
            - vehicles
            - activities
          type: string
      required:
        - type
        - value
      type: object
    Pickup:
      $ref: "#/components/schemas/Stop"
    Polygon:
      properties:
        coordinates:
          items:
            items:
              items:
                type: number
              type: array
            type: array
          type: array
        type:
          type: string
      type: object
    Request:
      example:
        configuration:
          routing:
            calc_points: true
            snap_preventions:
              - motorway
              - trunk
              - tunnel
              - bridge
              - ferry
        objectives:
          - type: min
            value: vehicles
          - type: min
            value: completion_time
        services:
          - address:
              lat: 52.537338
              location_id: 13.375854_52.537338
              lon: 13.375854
            id: s-1
            name: visit-Joe
            size:
              - 1
            time_windows:
              - earliest: 1554805329
                latest: 1554806329
          - address:
              lat: 52.525851
              location_id: 13.393364_52.525851
              lon: 13.393364
            id: s-2
            name: serve-Peter
            size:
              - 1
          - address:
              lat: 52.523543
              location_id: 13.416882_52.523543
              lon: 13.416882
            id: s-3
            name: visit-Michael
            size:
              - 1
          - address:
              lat: 52.514038
              location_id: 13.395767_52.514038
              lon: 13.395767
            id: s-4
            name: do nothing
            size:
              - 1
        shipments:
          - delivery:
              address:
                lat: 52.513614
                location_id: 13.380575_52.513614
                lon: 13.380575
            id: 7fe77504-7df8-4497-843c-02d70b6490ce
            name: pickup and deliver pizza to Peter
            pickup:
              address:
                lat: 52.529961
                location_id: 13.387613_52.529961
                lon: 13.387613
            priority: 1
            required_skills:
              - physical strength
            size:
              - 1
        vehicle_types:
          - capacity:
              - 10
            profile: bike
            type_id: cargo-bike
        vehicles:
          - earliest_start: 1554804329
            latest_end: 1554808329
            max_jobs: 3
            start_address:
              lat: 52.537
              location_id: berlin
              lon: 13.406
            type_id: cargo-bike
            vehicle_id: vehicle-1
          - earliest_start: 1554804329
            latest_end: 1554808329
            max_jobs: 3
            skills:
              - physical strength
            start_address:
              lat: 52.537
              location_id: berlin
              lon: 13.406
            type_id: cargo-bike
            vehicle_id: vehicle-2
      properties:
        algorithm:
          $ref: "#/components/schemas/Algorithm"
        configuration:
          $ref: "#/components/schemas/Configuration"
          description: Specifies general configurations.
        cost_matrices:
          description: Specifies your own tranport time and distance matrices.
          example:
            - data:
                distances:
                  - - 0
                    - 1000
                    - 1400
                    - 2000
                    - 0
                    - 4000
                  - - 1000
                    - 0
                    - 1000
                    - 2100
                    - 1000
                    - 4000
                  - - 1400
                    - 1000
                    - 0
                    - 1100
                    - 1100
                    - 4000
                  - - 2000
                    - 2100
                    - 1100
                    - 0
                    - 1200
                    - 4000
                  - - 0
                    - 1000
                    - 1400
                    - 2000
                    - 0
                    - 4000
                  - - 4000
                    - 4000
                    - 4000
                    - 4000
                    - 4000
                    - 4000
                times:
                  - - 0
                    - 1000
                    - 1400
                    - 2000
                    - 0
                    - 4000
                  - - 1000
                    - 0
                    - 1000
                    - 2100
                    - 1000
                    - 4000
                  - - 1400
                    - 1000
                    - 0
                    - 1100
                    - 1100
                    - 4000
                  - - 2000
                    - 2100
                    - 1100
                    - 0
                    - 1200
                    - 4000
                  - - 0
                    - 1000
                    - 1400
                    - 2000
                    - 0
                    - 4000
                  - - 4000
                    - 4000
                    - 4000
                    - 4000
                    - 4000
                    - 4000
              location_ids:
                - start
                - Dammstrasse
                - Bergstrasse
                - Koppstrasse
                - start2
                - nirvana
              profile: car
          items:
            $ref: "#/components/schemas/CostMatrix"
          type: array
        objectives:
          description: Specifies an objective function. The vehicle routing problem is solved in such a way that this objective function is minimized.
          example:
            - type: min
              value: vehicles
            - type: min
              value: completion_time
          items:
            $ref: "#/components/schemas/Objective"
          type: array
        relations:
          description: Defines additional relationships between orders.
          items:
            anyOf:
              - $ref: "#/components/schemas/JobRelation"
              - $ref: "#/components/schemas/GroupRelation"
          type: array
        services:
          description: Specifies the orders of the type "service". These are, for example, pick-ups, deliveries or other stops that are to be approached by the specified vehicles. Each of these orders contains only one location.
          items:
            $ref: "#/components/schemas/Service"
          type: array
        shipments:
          description: Specifies the available shipments. Each shipment contains a pickup and a delivery stop, which must be processed one after the other.
          items:
            $ref: "#/components/schemas/Shipment"
          type: array
        vehicle_types:
          description: Specifies the available vehicle types. These types can be assigned to vehicles.
          items:
            $ref: "#/components/schemas/VehicleType"
          type: array
        vehicles:
          description: Specifies the available vehicles.
          items:
            $ref: "#/components/schemas/Vehicle"
          minItems: 1
          type: array
      type: object
    Response:
      example:
        copyrights:
          - GraphHopper
          - OpenStreetMap contributors
        job_id: d62fcadd-c84a-4298-90b5-28550125bec5
        processing_time: 459
        solution:
          completion_time: 4172
          costs: 438
          distance: 17994
          max_operation_time: 2465
          no_unassigned: 0
          no_vehicles: 2
          preparation_time: 0
          routes:
            - activities:
                - address:
                    lat: 52.537
                    location_id: berlin
                    lon: 13.406
                  distance: 0
                  driving_time: 0
                  end_date_time: null
                  end_time: 1554804329
                  load_after:
                    - 0
                  location_id: berlin
                  preparation_time: 0
                  type: start
                  waiting_time: 0
                - address:
                    lat: 52.529961
                    location_id: 13.387613_52.529961
                    lon: 13.387613
                  arr_date_time: null
                  arr_time: 1554804789
                  distance: 2012
                  driving_time: 460
                  end_date_time: null
                  end_time: 1554804789
                  id: 7fe77504-7df8-4497-843c-02d70b6490ce
                  load_after:
                    - 1
                  load_before:
                    - 0
                  location_id: 13.387613_52.529961
                  preparation_time: 0
                  type: pickupShipment
                  waiting_time: 0
                - address:
                    lat: 52.513614
                    location_id: 13.380575_52.513614
                    lon: 13.380575
                  arr_date_time: null
                  arr_time: 1554805344
                  distance: 4560
                  driving_time: 1015
                  end_date_time: null
                  end_time: 1554805344
                  id: 7fe77504-7df8-4497-843c-02d70b6490ce
                  load_after:
                    - 0
                  load_before:
                    - 1
                  location_id: 13.380575_52.513614
                  preparation_time: 0
                  type: deliverShipment
                  waiting_time: 0
                - address:
                    lat: 52.514038
                    location_id: 13.395767_52.514038
                    lon: 13.395767
                  arr_date_time: null
                  arr_time: 1554805632
                  distance: 5887
                  driving_time: 1303
                  end_date_time: null
                  end_time: 1554805632
                  id: s-4
                  load_after:
                    - 1
                  load_before:
                    - 0
                  location_id: 13.395767_52.514038
                  preparation_time: 0
                  type: service
                  waiting_time: 0
                - address:
                    lat: 52.523543
                    location_id: 13.416882_52.523543
                    lon: 13.416882
                  arr_date_time: null
                  arr_time: 1554806253
                  distance: 8486
                  driving_time: 1924
                  end_date_time: null
                  end_time: 1554806253
                  id: s-3
                  load_after:
                    - 2
                  load_before:
                    - 1
                  location_id: 13.416882_52.523543
                  preparation_time: 0
                  type: service
                  waiting_time: 0
                - address:
                    lat: 52.537
                    location_id: berlin
                    lon: 13.406
                  arr_date_time: null
                  arr_time: 1554806794
                  distance: 10618
                  driving_time: 2465
                  load_before:
                    - 2
                  location_id: berlin
                  preparation_time: 0
                  type: end
                  waiting_time: 0
              completion_time: 2465
              distance: 10618
              points:
                - coordinates:
                    - - 13.40608
                      - 52.53701
                    - - 13.40643
                      - 52.53631
                    - - 13.40554
                      - 52.53616
                    - - 13.4054
                      - 52.53608
                    - - 13.40445
                      - 52.53513
                    - - 13.40436
                      - 52.53509
                    - - 13.40428
                      - 52.53508
                    - - 13.40463
                      - 52.53419
                    - - 13.40451
                      - 52.53419
                    - - 13.4034
                      - 52.53401
                    - - 13.403
                      - 52.53359
                    - - 13.40291
                      - 52.53354
                    - - 13.40268
                      - 52.53347
                    - - 13.39888
                      - 52.53259
                    - - 13.39839
                      - 52.53253
                    - - 13.39812
                      - 52.53251
                    - - 13.39616
                      - 52.53243
                    - - 13.39579
                      - 52.5324
                    - - 13.38973
                      - 52.53173
                    - - 13.39163
                      - 52.53025
                    - - 13.38797
                      - 52.52935
                    - - 13.38763
                      - 52.52996
                  type: LineString
                - coordinates:
                    - - 13.38763
                      - 52.52996
                    - - 13.38739
                      - 52.53039
                    - - 13.38724
                      - 52.53036
                    - - 13.38464
                      - 52.52929
                    - - 13.38538
                      - 52.52871
                    - - 13.38634
                      - 52.52792
                    - - 13.38638
                      - 52.52779
                    - - 13.38657
                      - 52.52763
                    - - 13.38676
                      - 52.52741
                    - - 13.38698
                      - 52.52713
                    - - 13.38704
                      - 52.52701
                    - - 13.38753
                      - 52.524
                    - - 13.3877
                      - 52.52307
                    - - 13.3878
                      - 52.52282
                    - - 13.38788
                      - 52.52252
                    - - 13.38802
                      - 52.52174
                    - - 13.38519
                      - 52.52009
                    - - 13.38539
                      - 52.5191
                    - - 13.38548
                      - 52.51852
                    - - 13.38042
                      - 52.51819
                    - - 13.38071
                      - 52.5167
                    - - 13.38076
                      - 52.51652
                    - - 13.38084
                      - 52.51634
                    - - 13.3821
                      - 52.51396
                    - - 13.38055
                      - 52.51365
                  type: LineString
                - coordinates:
                    - - 13.38055
                      - 52.51365
                    - - 13.38229
                      - 52.514
                    - - 13.38363
                      - 52.51429
                    - - 13.3848
                      - 52.51445
                    - - 13.38504
                      - 52.51358
                    - - 13.39124
                      - 52.51397
                    - - 13.3911
                      - 52.51488
                    - - 13.39303
                      - 52.51499
                    - - 13.39317
                      - 52.5141
                    - - 13.39548
                      - 52.51419
                    - - 13.39571
                      - 52.51421
                  type: LineString
                - coordinates:
                    - - 13.39571
                      - 52.51421
                    - - 13.39695
                      - 52.51434
                    - - 13.39674
                      - 52.51523
                    - - 13.39742
                      - 52.51531
                    - - 13.39873
                      - 52.51558
                    - - 13.39846
                      - 52.51599
                    - - 13.39825
                      - 52.51729
                    - - 13.39805
                      - 52.51755
                    - - 13.39892
                      - 52.51761
                    - - 13.39917
                      - 52.51764
                    - - 13.39964
                      - 52.51775
                    - - 13.40009
                      - 52.51791
                    - - 13.40034
                      - 52.51797
                    - - 13.4021
                      - 52.51864
                    - - 13.40288
                      - 52.51896
                    - - 13.40375
                      - 52.51936
                    - - 13.40498
                      - 52.52001
                    - - 13.40463
                      - 52.5203
                    - - 13.40311
                      - 52.52144
                    - - 13.40442
                      - 52.52189
                    - - 13.40448
                      - 52.52192
                    - - 13.40451
                      - 52.52195
                    - - 13.40473
                      - 52.52199
                    - - 13.40504
                      - 52.52208
                    - - 13.40572
                      - 52.52235
                    - - 13.40687
                      - 52.52294
                    - - 13.40693
                      - 52.52299
                    - - 13.40706
                      - 52.52319
                    - - 13.40738
                      - 52.52378
                    - - 13.40787
                      - 52.52443
                    - - 13.4079
                      - 52.52453
                    - - 13.40938
                      - 52.52401
                    - - 13.40962
                      - 52.52398
                    - - 13.41001
                      - 52.52395
                    - - 13.41072
                      - 52.52391
                    - - 13.41215
                      - 52.52389
                    - - 13.41233
                      - 52.52386
                    - - 13.4131
                      - 52.5235
                    - - 13.41288
                      - 52.52333
                    - - 13.41475
                      - 52.52247
                    - - 13.41496
                      - 52.52264
                    - - 13.41523
                      - 52.52251
                    - - 13.41633
                      - 52.52338
                    - - 13.41631
                      - 52.52346
                    - - 13.41654
                      - 52.52364
                    - - 13.41684
                      - 52.52351
                  type: LineString
                - coordinates:
                    - - 13.41684
                      - 52.52351
                    - - 13.41654
                      - 52.52364
                    - - 13.41631
                      - 52.52346
                    - - 13.4163
                      - 52.52344
                    - - 13.41587
                      - 52.52363
                    - - 13.41572
                      - 52.5235
                    - - 13.41409
                      - 52.5242
                    - - 13.41454
                      - 52.52461
                    - - 13.41454
                      - 52.52466
                    - - 13.41358
                      - 52.52508
                    - - 13.41366
                      - 52.52514
                    - - 13.41344
                      - 52.52525
                    - - 13.4133
                      - 52.52514
                    - - 13.41316
                      - 52.5252
                    - - 13.41107
                      - 52.52585
                    - - 13.41118
                      - 52.52606
                    - - 13.41118
                      - 52.52616
                    - - 13.41095
                      - 52.52664
                    - - 13.41097
                      - 52.52678
                    - - 13.41084
                      - 52.52706
                    - - 13.41057
                      - 52.52747
                    - - 13.41028
                      - 52.52809
                    - - 13.41032
                      - 52.52821
                    - - 13.4102
                      - 52.52847
                    - - 13.40999
                      - 52.52875
                    - - 13.40984
                      - 52.52905
                    - - 13.40982
                      - 52.52914
                    - - 13.40984
                      - 52.52926
                    - - 13.4104
                      - 52.52998
                    - - 13.4105
                      - 52.53001
                    - - 13.41064
                      - 52.53016
                    - - 13.41082
                      - 52.5303
                    - - 13.41198
                      - 52.53107
                    - - 13.4122
                      - 52.53128
                    - - 13.41232
                      - 52.53143
                    - - 13.41247
                      - 52.53192
                    - - 13.41267
                      - 52.53245
                    - - 13.41275
                      - 52.53259
                    - - 13.41215
                      - 52.5327
                    - - 13.40731
                      - 52.53463
                    - - 13.40608
                      - 52.53701
                  type: LineString
              preparation_time: 0
              service_duration: 0
              transport_time: 2465
              vehicle_id: vehicle-2
              waiting_time: 0
            - activities:
                - address:
                    lat: 52.537
                    location_id: berlin
                    lon: 13.406
                  distance: 0
                  driving_time: 0
                  end_date_time: null
                  end_time: 1554804329
                  load_after:
                    - 0
                  location_id: berlin
                  preparation_time: 0
                  type: start
                  waiting_time: 0
                - address:
                    lat: 52.525851
                    location_id: 13.393364_52.525851
                    lon: 13.393364
                  arr_date_time: null
                  arr_time: 1554804743
                  distance: 1884
                  driving_time: 414
                  end_date_time: null
                  end_time: 1554804743
                  id: s-2
                  load_after:
                    - 1
                  load_before:
                    - 0
                  location_id: 13.393364_52.525851
                  preparation_time: 0
                  type: service
                  waiting_time: 0
                - address:
                    lat: 52.537338
                    location_id: 13.375854_52.537338
                    lon: 13.375854
                  arr_date_time: null
                  arr_time: 1554805251
                  distance: 4205
                  driving_time: 922
                  end_date_time: null
                  end_time: 1554805329
                  id: s-1
                  load_after:
                    - 2
                  load_before:
                    - 1
                  location_id: 13.375854_52.537338
                  preparation_time: 0
                  type: service
                  waiting_time: 78
                - address:
                    lat: 52.537
                    location_id: berlin
                    lon: 13.406
                  arr_date_time: null
                  arr_time: 1554806036
                  distance: 7376
                  driving_time: 1629
                  load_before:
                    - 2
                  location_id: berlin
                  preparation_time: 0
                  type: end
                  waiting_time: 0
              completion_time: 1707
              distance: 7376
              points:
                - coordinates:
                    - - 13.40608
                      - 52.53701
                    - - 13.40674
                      - 52.53571
                    - - 13.40433
                      - 52.53313
                    - - 13.40271
                      - 52.53149
                    - - 13.40246
                      - 52.53121
                    - - 13.40148
                      - 52.52999
                    - - 13.40128
                      - 52.52993
                    - - 13.40118
                      - 52.52988
                    - - 13.40133
                      - 52.5296
                    - - 13.40138
                      - 52.52951
                    - - 13.40167
                      - 52.52914
                    - - 13.40188
                      - 52.52895
                    - - 13.398
                      - 52.52885
                    - - 13.39289
                      - 52.52748
                    - - 13.39354
                      - 52.5264
                    - - 13.39358
                      - 52.52628
                    - - 13.39324
                      - 52.52575
                    - - 13.39334
                      - 52.52573
                    - - 13.39339
                      - 52.52584
                  type: LineString
                - coordinates:
                    - - 13.39339
                      - 52.52584
                    - - 13.3934
                      - 52.52599
                    - - 13.39358
                      - 52.52628
                    - - 13.39354
                      - 52.5264
                    - - 13.39242
                      - 52.52823
                    - - 13.39381
                      - 52.52852
                    - - 13.38973
                      - 52.53173
                    - - 13.38717
                      - 52.5315
                    - - 13.38678
                      - 52.5315
                    - - 13.38641
                      - 52.53147
                    - - 13.38617
                      - 52.53143
                    - - 13.38607
                      - 52.53155
                    - - 13.38526
                      - 52.53225
                    - - 13.38501
                      - 52.53252
                    - - 13.38316
                      - 52.53418
                    - - 13.38179
                      - 52.5355
                    - - 13.38084
                      - 52.53523
                    - - 13.38081
                      - 52.53531
                    - - 13.3795
                      - 52.53677
                    - - 13.37941
                      - 52.53682
                    - - 13.37935
                      - 52.53683
                    - - 13.37919
                      - 52.53682
                    - - 13.37617
                      - 52.5361
                    - - 13.37502
                      - 52.53698
                    - - 13.37584
                      - 52.53734
                  type: LineString
                - coordinates:
                    - - 13.37584
                      - 52.53734
                    - - 13.37566
                      - 52.53726
                    - - 13.37515
                      - 52.53763
                    - - 13.37644
                      - 52.53841
                    - - 13.37807
                      - 52.53935
                    - - 13.37946
                      - 52.5402
                    - - 13.3796
                      - 52.54019
                    - - 13.37984
                      - 52.54021
                    - - 13.37988
                      - 52.54012
                    - - 13.38062
                      - 52.53936
                    - - 13.38169
                      - 52.53832
                    - - 13.38236
                      - 52.5377
                    - - 13.38363
                      - 52.53661
                    - - 13.38492
                      - 52.53555
                    - - 13.38613
                      - 52.53447
                    - - 13.38757
                      - 52.53338
                    - - 13.38791
                      - 52.53354
                    - - 13.38812
                      - 52.53368
                    - - 13.38833
                      - 52.53392
                    - - 13.38977
                      - 52.53518
                    - - 13.39003
                      - 52.53539
                    - - 13.39256
                      - 52.53701
                    - - 13.39316
                      - 52.53739
                    - - 13.39327
                      - 52.53744
                    - - 13.3936
                      - 52.53757
                    - - 13.40155
                      - 52.53982
                    - - 13.40357
                      - 52.53715
                    - - 13.40372
                      - 52.53719
                    - - 13.40465
                      - 52.53727
                    - - 13.4048
                      - 52.53726
                    - - 13.4059
                      - 52.53736
                    - - 13.40608
                      - 52.53701
                  type: LineString
              preparation_time: 0
              service_duration: 0
              transport_time: 1629
              vehicle_id: vehicle-1
              waiting_time: 78
          service_duration: 0
          time: 4094
          transport_time: 4094
          unassigned:
            breaks: []
            details: []
            services: []
            shipments: []
          waiting_time: 78
        status: finished
        waiting_time_in_queue: 0
      properties:
        copyrights:
          example:
            - GraphHopper
            - OpenStreetMap contributors
          items:
            description: Attribution
            type: string
          type: array
        processing_time:
          description: Processing time in ms. If job is still waiting in queue, processing_time is 0
          example: 900000
          format: int64
          type: integer
        solution:
          $ref: "#/components/schemas/Solution"
        status:
          description: Indicates the current status of the job
          enum:
            - waiting_in_queue
            - processing
            - finished
          example: finished
          type: string
        waiting_time_in_queue:
          description: Waiting time in ms
          example: 300000
          format: int64
          type: integer
      type: object
    ResponseAddress:
      description: Address of activity
      properties:
        lat:
          description: Latitude of location.
          example: 51.512665
          format: double
          type: number
        location_id:
          description: Specifies the id of the location.
          example: 550e8400-e29b-11d4-a716-446655440000
          type: string
        lon:
          description: Longitude of location.
          example: -0.092869
          format: double
          type: number
        name:
          description: Name of location.
          example: Queens Victoria Street 70, Second Floor, Flat 245
          type: string
        snapped_waypoint:
          $ref: "#/components/schemas/SnappedWaypoint"
        street_hint:
          description: Optional parameter. Specifies a hint for each address to better snap the coordinates (lon,lat) to road network. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.
          example: Queens Victoria Street 70
          type: string
      type: object
    ResponseInfo:
      description: Additional information for your request
      properties:
        copyrights:
          description: Attribution according to our documentation is necessary if no white-label option included.
          items:
            type: string
          type: array
        took:
          format: double
          type: number
      type: object
    Route:
      properties:
        activities:
          description: Array of activities
          example:
            - address:
                lat: 52.537
                location_id: berlin
                lon: 13.406
              distance: 0
              driving_time: 0
              end_date_time: 2019-02-25T20:20+01:00
              end_time: 1551122400
              load_after:
                - 0
              location_id: berlin
              preparation_time: 0
              type: start
              waiting_time: 0
            - address:
                lat: 52.527094
                location_id: 13.408642_52.527094
                lon: 13.408642
              arr_date_time: 2019-02-25T20:25:13+01:00
              arr_time: 1551122713
              distance: 1777
              driving_time: 313
              end_date_time: 2019-02-25T20:25:13+01:00
              end_time: 1551122713
              id: berlin-2
              load_after:
                - 0
              load_before:
                - 0
              location_id: 13.408642_52.527094
              preparation_time: 0
              type: service
              waiting_time: 0
            - address:
                lat: 52.527303
                location_id: 13.398170_52.527303
                lon: 13.39817
              arr_date_time: 2019-02-25T20:27:44+01:00
              arr_time: 1551122864
              distance: 2562
              driving_time: 464
              end_date_time: 2019-02-25T20:27:44+01:00
              end_time: 1551122864
              id: berlin-1
              load_after:
                - 0
              load_before:
                - 0
              location_id: 13.398170_52.527303
              preparation_time: 0
              type: service
              waiting_time: 0
            - address:
                lat: 52.537
                location_id: berlin
                lon: 13.406
              arr_date_time: 2019-02-25T20:33:09+01:00
              arr_time: 1551123189
              distance: 4334
              driving_time: 789
              load_before:
                - 0
              location_id: berlin
              preparation_time: 0
              type: end
              waiting_time: 0
          items:
            $ref: "#/components/schemas/Activity"
          type: array
        completion_time:
          description: Completion time of route in seconds
          example: 1800
          format: int64
          type: integer
        distance:
          description: Distance of route in meter
          example: 10000
          format: int64
          type: integer
        points:
          description: Array of route planning points
          example:
            - coordinates:
                - - 13.4061
                  - 52.53701
                - - 13.40643
                  - 52.53634
                - - 13.4067
                  - 52.53573
                - - 13.40722
                  - 52.53479
                - - 13.40729
                  - 52.53468
                - - 13.40735
                  - 52.53463
                - - 13.41205
                  - 52.53275
                - - 13.41245
                  - 52.53264
                - - 13.41218
                  - 52.53166
                - - 13.41205
                  - 52.53139
                - - 13.41177
                  - 52.53112
                - - 13.41072
                  - 52.53033
                - - 13.41049
                  - 52.53014
                - - 13.4098
                  - 52.52928
                - - 13.40937
                  - 52.5287
                - - 13.40994
                  - 52.52858
                - - 13.41032
                  - 52.52782
                - - 13.41054
                  - 52.52745
                - - 13.41097
                  - 52.52656
                - - 13.41107
                  - 52.5265
                - - 13.41119
                  - 52.52614
                - - 13.41119
                  - 52.52604
                - - 13.41109
                  - 52.52587
                - - 13.40971
                  - 52.52631
                - - 13.40981
                  - 52.52659
                - - 13.40891
                  - 52.52683
                - - 13.40852
                  - 52.52695
              type: LineString
            - coordinates:
                - - 13.40852
                  - 52.52695
                - - 13.4081
                  - 52.52706
                - - 13.40802
                  - 52.52696
                - - 13.40469
                  - 52.52758
                - - 13.4033
                  - 52.52781
                - - 13.40331
                  - 52.52767
                - - 13.40298
                  - 52.52763
                - - 13.40261
                  - 52.52807
                - - 13.39818
                  - 52.52726
              type: LineString
            - coordinates:
                - - 13.39818
                  - 52.52726
                - - 13.39808
                  - 52.52725
                - - 13.39785
                  - 52.52768
                - - 13.39727
                  - 52.52866
                - - 13.39762
                  - 52.52876
                - - 13.3976
                  - 52.52914
                - - 13.39756
                  - 52.52943
                - - 13.39597
                  - 52.53243
                - - 13.39777
                  - 52.5325
                - - 13.39843
                  - 52.53254
                - - 13.39891
                  - 52.53259
                - - 13.40288
                  - 52.53354
                - - 13.40297
                  - 52.53359
                - - 13.40338
                  - 52.534
                - - 13.40466
                  - 52.53419
                - - 13.40433
                  - 52.53503
                - - 13.40443
                  - 52.53511
                - - 13.40541
                  - 52.53611
                - - 13.40547
                  - 52.53615
                - - 13.40643
                  - 52.53634
                - - 13.4061
                  - 52.53701
              type: LineString
          items:
            $ref: "#/components/schemas/RoutePoint"
          type: array
        preparation_time:
          description: Preparation time of route in seconds
          format: int64
          type: integer
        service_duration:
          description: Service duration of route in seconds
          format: int64
          type: integer
        transport_time:
          description: Transport time of route in seconds
          example: 1800
          format: int64
          type: integer
        vehicle_id:
          description: Id of vehicle that operates route
          example: driver-stefan
          type: string
        waiting_time:
          description: Waiting time of route in seconds
          format: int64
          type: integer
      type: object
    RoutePoint:
      properties:
        coordinates:
          items:
            type: object
          type: array
        type:
          type: string
      type: object
    RouteRequest:
      example:
        calc_points: true
        details:
          - road_class
          - surface
        instructions: true
        locale: en
        point_hints:
          - Lindenschmitstraße
          - Thalkirchener Str.
        points:
          - - 11.539421
            - 48.118477
          - - 11.559023
            - 48.12228
        points_encoded: false
        snap_preventions:
          - motorway
          - ferry
          - tunnel
        vehicle: bike
      properties:
        algorithm:
          description: |
            Rather than looking for the shortest or fastest path, this lets you solve two different problems related to routing:
            With `round_trip`, the route will get you back to where you started. This is meant for fun (think of
            a bike trip), so we will add some randomness. This requires `ch.disable=true`.
            With `alternative_route`, we give you not one but several routes that are close to optimal, but
            not too similar to each other. You can control both of these features with additional parameters, see below.
          enum:
            - round_trip
            - alternative_route
          type: string
        alternative_route.max_paths:
          default: 2
          description: |
            If `algorithm=alternative_route`, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.
          format: int32
          type: integer
        alternative_route.max_share_factor:
          default: 0.6
          description: |
            If `algorithm=alternative_route`, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.
          type: number
        alternative_route.max_weight_factor:
          default: 1.4
          description: |
            If `algorithm=alternative_route`, this parameter sets the factor by which the alternatives routes can be longer than the optimal route. Increasing can lead to worse alternatives.
          type: number
        avoid:
          description: |
            Specify which road classes and environments you would like to avoid.
            Possible values are `motorway`, `steps`, `track`, `toll`, `ferry`, `tunnel` and `bridge`.
            Separate several values with `;`. Obviously not all the values make sense for all vehicle profiles e.g. `bike` is already forbidden on a `motorway`. Requires `ch.disable=true`.
          type: string
        block_area:
          description: |
            Block road access via a point with the format `latitude,longitude`
            or an area defined by a circle `lat,lon,radius` or a rectangle `lat1,lon1,lat2,lon2`.
            Separate several values with `;`. Requires `ch.disable=true`.
          type: string
        calc_points:
          default: true
          description: |
            If the points for the route should be calculated at all.
          type: boolean
        ch.disable:
          default: false
          description: |
            Use this parameter in combination with one or more parameters from below.
          type: boolean
        curbsides:
          description: Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap.
          example:
            - any
            - right
          items:
            enum:
              - any
              - right
              - left
            type: string
          type: array
        debug:
          default: false
          description: |
            If `true`, the output will be formatted.
          type: boolean
        details:
          description: |
            Optional parameter to retrieve path details. You can request additional details for the route: `street_name`,
            `time`, `distance`, `max_speed`, `toll`, `road_class`, `road_class_link`, `road_access`, `road_environment`, `lanes`, and `surface`. Read more about the usage of path details [here](https://discuss.graphhopper.com/t/2539).
          items:
            type: string
          type: array
        elevation:
          default: false
          description: |
            If `true`, a third coordinate, the altitude, is included with all positions in the response.
            This changes the format of the `points` and `snapped_waypoints` fields of the response, in both their
            encodings. Unless you switch off the `points_encoded` parameter, you need special code on the
            client side that can handle three-dimensional coordinates.
            A request can fail if the vehicle profile does not support elevation. See the features object for every vehicle profile.
          type: boolean
        heading_penalty:
          default: 120
          description: |
            Time penalty in seconds for not obeying a specified heading. Requires `ch.disable=true`.
          format: int32
          type: integer
        headings:
          description: |
            Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.
            In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.
            This parameter also influences the tour generated with `algorithm=round_trip` and forces the initial direction.  Requires `ch.disable=true`.
          items:
            format: int32
            type: integer
          type: array
        instructions:
          default: true
          description: |
            If instructions should be calculated and returned
          type: boolean
        locale:
          default: en
          description: |
            The locale of the resulting turn instructions. E.g. `pt_PT` for Portuguese or `de` for German.
          type: string
        optimize:
          default: "false"
          description: |
            Normally, the calculated route will visit the points in the order you specified them.
            If you have more than two points, you can set this parameter to `"true"` and the points may be re-ordered to minimize the total travel time.
            Keep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.
          type: string
        pass_through:
          default: false
          description: |
            If `true`, u-turns are avoided at via-points with regard to the `heading_penalty`. Requires `ch.disable=true`.
          type: boolean
        point_hints:
          description: Optional parameter. Specifies a hint for each point in the `points` array to prefer a certain street for the closest location lookup. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.
          example:
            - Lindenschmitstraße
            - Thalkirchener Str.
          items:
            type: string
          type: array
        points:
          description: |
            The points for the route in an array of `[longitude,latitude]`. For instance, if you want to calculate a route from point A to B to C
            then you specify `points: [ [A_longitude, A_latitude], [B_longitude, B_latitude], [C_longitude, C_latitude]]
          example:
            - - 11.539421
              - 48.118477
            - - 11.559023
              - 48.12228
          items:
            items:
              format: double
              type: number
            type: array
          type: array
        points_encoded:
          default: true
          description: |
            Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact
            but requires special client code to unpack. (We provide it in our JavaScript client library!)
            Set this parameter to `false` to switch the encoding to simple coordinate pairs like `[lon,lat]`, or `[lon,lat,elevation]`.
            See the description of the response format for more information.
          type: boolean
        round_trip.distance:
          default: 10000
          description: |
            If `algorithm=round_trip`, this parameter configures approximative length of the resulting round trip. Requires `ch.disable=true`.
          format: int32
          type: integer
        round_trip.seed:
          description: |
            If `algorithm=round_trip`, this sets the random seed. Change this to get a different tour for each value.
          format: int64
          type: integer
        snap_preventions:
          description: Optional parameter to avoid snapping to a certain road class or road environment. Current supported values `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`
          example:
            - motorway
            - ferry
            - tunnel
          items:
            type: string
          type: array
        vehicle:
          allOf:
            - $ref: "#/components/schemas/VehicleProfileId"
            - description: The vehicle profile for which the route should be calculated. Other vehicles are listed [here](#section/Map-Data-and-Routing-Profiles/OpenStreetMap) for the details.
          example: bike
        weighting:
          default: fastest
          description: |
            Determines the way the ''best'' route is calculated. Default is `fastest`. Other options are `shortest` (e.g. for `vehicle=foot` or `bike`) and `short_fastest` which finds a reasonable balance between `shortest` and `fastest`. Requires `ch.disable=true`.
          type: string
      type: object
    RouteResponse:
      example:
        hints:
          visited_nodes.average: 58
          visited_nodes.sum: 58
        info:
          copyrights:
            - GraphHopper
            - OpenStreetMap contributors
          took: 2
        paths:
          - ascend: 6.3294677734375
            bbox:
              - 11.539424
              - 48.118343
              - 11.558901
              - 48.122364
            descend: 25.0579833984375
            details: {}
            distance: 1791.011
            instructions:
              - distance: 672.954
                heading: 89.04
                interval:
                  - 0
                  - 6
                sign: 0
                street_name: Lindenschmitstraße
                text: Continue onto Lindenschmitstraße
                time: 144703
              - distance: 107.145
                interval:
                  - 6
                  - 7
                sign: -2
                street_name: ""
                text: Turn left
                time: 22675
              - distance: 140.169
                interval:
                  - 7
                  - 10
                sign: 2
                street_name: Oberländerstraße
                text: Turn right onto Oberländerstraße
                time: 28032
              - distance: 360.232
                interval:
                  - 10
                  - 18
                sign: 1
                street_name: ""
                text: Turn slight right
                time: 72677
              - distance: 177.621
                interval:
                  - 18
                  - 20
                sign: 2
                street_name: Thalkirchner Straße
                text: Turn right onto Thalkirchner Straße
                time: 35524
              - distance: 332.89
                interval:
                  - 20
                  - 24
                sign: -2
                street_name: Thalkirchner Straße
                text: Turn left onto Thalkirchner Straße
                time: 67351
              - distance: 0
                interval:
                  - 24
                  - 24
                last_heading: 45.67046584987792
                sign: 4
                street_name: ""
                text: Arrive at destination
                time: 0
            legs: []
            points:
              coordinates:
                - - 11.539424
                  - 48.118352
                - - 11.540387
                  - 48.118368
                - - 11.54061
                  - 48.118356
                - - 11.541941
                  - 48.118409
                - - 11.543696
                  - 48.118344
                - - 11.547167
                  - 48.118343
                - - 11.548478
                  - 48.118366
                - - 11.548487
                  - 48.119329
                - - 11.548807
                  - 48.119328
                - - 11.549408
                  - 48.119366
                - - 11.550349
                  - 48.119508
                - - 11.550441
                  - 48.119473
                - - 11.551109
                  - 48.119467
                - - 11.551553
                  - 48.119445
                - - 11.551748
                  - 48.119398
                - - 11.552087
                  - 48.119475
                - - 11.552236
                  - 48.119542
                - - 11.552353
                  - 48.119635
                - - 11.553853
                  - 48.121136
                - - 11.555448
                  - 48.12039
                - - 11.555797
                  - 48.120206
                - - 11.55632
                  - 48.120592
                - - 11.556716
                  - 48.120919
                - - 11.557326
                  - 48.121345
                - - 11.558901
                  - 48.122364
              type: LineString
            points_encoded: false
            snapped_waypoints:
              coordinates:
                - - 11.539424
                  - 48.118352
                - - 11.558901
                  - 48.122364
              type: LineString
            time: 370962
            transfers: 0
            weight: 307.852443
      properties:
        info:
          $ref: "#/components/schemas/ResponseInfo"
        paths:
          items:
            $ref: "#/components/schemas/RouteResponsePath"
          type: array
      type: object
    RouteResponsePath:
      properties:
        ascend:
          description: |
            The total ascent, in meters.
          format: double
          type: number
        bbox:
          description: |
            The bounding box of the route geometry. Format: `[minLon, minLat, maxLon, maxLat]`.
          items:
            format: double
            type: number
          type: array
        descend:
          description: |
            The total descent, in meters.
          format: double
          type: number
        details:
          description: |
            Details, as requested with the `details` parameter. Consider the value `{"street_name": [[0,2,"Frankfurter Straße"],[2,6,"Zollweg"]]}`.
            In this example, the route uses two streets: The first, Frankfurter Straße, is
            used between `points[0]` and `points[2]`, and the second, Zollweg, between `points[2]` and `points[6]`.
            See [here](https://discuss.graphhopper.com/t/2539) for discussion.
          type: object
        distance:
          description: |
            The total distance, in meters. To get this information for one 'leg' please read [this blog post](https://www.graphhopper.com/blog/2019/11/28/routing-api-using-path-details/).
          format: double
          type: number
        instructions:
          description: |
            The instructions for this route. This feature is under active development, and our instructions can sometimes be misleading,
            so be mindful when using them for navigation.
          items:
            properties:
              distance:
                description: |
                  The distance for this instruction, in meters.
                format: double
                type: number
              exit_number:
                description: |
                  Only available for roundabout instructions (sign is 6). The count of exits at which the route leaves the roundabout.
                format: int32
                type: integer
              interval:
                description: |
                  Two indices into `points`, referring to the beginning and the end of the segment of the route
                  this instruction refers to.
                items:
                  format: int32
                  type: integer
                type: array
              sign:
                description: |
                  A number which specifies the sign to show:

                  | sign | description  |
                  |---|---|
                  |-98| an U-turn without the knowledge if it is a right or left U-turn |
                  | -8| a left U-turn |
                  | -7| keep left |
                  | -6| **not yet used**: leave roundabout |
                  | -3| turn sharp left |
                  | -2| turn left |
                  | -1| turn slight left |
                  |  0| continue on street |
                  |  1| turn slight right |
                  |  2| turn right |
                  |  3| turn sharp right |
                  |  4| the finish instruction before the last point |
                  |  5| the instruction before a via point |
                  |  6| the instruction before entering a roundabout |
                  |  7| keep right |
                  |  8| a right U-turn |
                  |  *| **For future compatibility** it is important that all clients are able to handle also unknown instruction sign numbers
                format: int32
                type: integer
              street_name:
                description: |
                  The name of the street to turn onto in order to follow the route.
                type: string
              text:
                description: |
                  A description what the user has to do in order to follow the route. The language depends on the locale parameter.
                type: string
              time:
                description: |
                  The duration for this instruction, in milliseconds.
                format: int32
                type: integer
              turn_angle:
                description: |
                  Only available for roundabout instructions (sign is 6). The radian of the route within the roundabout `0 < r < 2*PI` for clockwise and
                  `-2*PI < r < 0` for counterclockwise turns.
                format: double
                type: number
            type: object
          type: array
        points:
          allOf:
            - description: |
                The geometry of the route. The format depends on the value of `points_encoded`.
            - anyOf:
                - $ref: "#/components/schemas/EncodedLineString"
                - $ref: "#/components/schemas/LineString"
        points_encoded:
          description: |
            Whether the `points` and `snapped_waypoints` fields are polyline-encoded strings rather than JSON arrays
            of coordinates. See the field description for more information on the two formats.
          type: boolean
        points_order:
          description: |
            An array of indices (zero-based), specifiying the order in which the input points are visited.
            Only present if the `optimize` parameter was used.
          items:
            type: integer
          type: array
        snapped_waypoints:
          allOf:
            - description: |
                The snapped input points. The format depends on the value of `points_encoded`.
            - anyOf:
                - $ref: "#/components/schemas/EncodedLineString"
                - $ref: "#/components/schemas/LineString"
        time:
          description: |
            The total travel time, in milliseconds. To get this information for one 'leg' please read [this blog post](https://www.graphhopper.com/blog/2019/11/28/routing-api-using-path-details/).
          format: int64
          type: integer
      type: object
    Routing:
      description: This contains all routing specific configurations.
      properties:
        calc_points:
          default: false
          description: It lets you specify whether the API should provide you with route geometries for vehicle routes or not. Thus, you do not need to do extra routing to get the polyline for each route.
          type: boolean
        consider_traffic:
          default: false
          description: indicates whether historical traffic information should be considered
          type: boolean
        curbside_strictness:
          default: soft
          description: In some cases curbside constraints cannot be fulfilled. For example in one-way streets you cannot arrive at a building that is on the left side of the street such that the building is to the right of you (unless you drove the one-way street the wrong/illegal way). You can set the `curbside_strictness` to `soft` to ignore the curbside constraint in such cases or set it to `strict` to get an error response instead. You can also set it to `ignore` to ignore all curbside constraints (this is useful to compare the results with and without constraints without modifying every single address).
          enum:
            - ignore
            - soft
            - strict
          type: string
        fail_fast:
          default: true
          description: indicates whether matrix calculation should fail fast when points cannot be connected
          type: boolean
        network_data_provider:
          default: openstreetmap
          description: specifies the data provider, read more about it [here](#section/Map-Data-and-Routing-Profiles).
          enum:
            - openstreetmap
            - tomtom
          type: string
        return_snapped_waypoints:
          default: false
          description: Indicates whether a solution includes snapped waypoints. In contrary to the address coordinate a snapped waypoint is the access point to the (road) network.
          type: boolean
        snap_preventions:
          description: Prevents snapping locations to road links of specified road types, e.g. to motorway.
          example:
            - motorway
            - trunk
            - bridge
            - tunnel
            - ferry
          items:
            enum:
              - motorway
              - trunk
              - bridge
              - ford
              - tunnel
              - ferry
            type: string
          type: array
      type: object
    Service:
      properties:
        address:
          $ref: "#/components/schemas/Address"
        allowed_vehicles:
          description: 'Specifies an array of allowed vehicles, i.e. array of vehicle ids. For example, if this service can only be conducted EITHER by `technician_peter` OR `technician_stefan` specify this as follows: `["technician_peter","technician_stefan"]`.'
          example:
            - technician_peter
            - technician_stefan
          items:
            type: string
          type: array
        disallowed_vehicles:
          description: Specifies an array of disallowed vehicles, i.e. array of vehicle ids.
          example:
            - driver-A
            - driver-B
          items:
            type: string
          type: array
        duration:
          default: 0
          description: Specifies the duration of the service in seconds, i.e. how long it takes at the customer site.
          example: 1800
          format: int64
          maximum: 604800
          minimum: 0
          type: integer
        group:
          description: Group this service belongs to. See the group relation and [this post](https://discuss.graphhopper.com/t/4040) on how to utilize this.
          example: group-A
          type: string
        id:
          description: Specifies the id of the service. Ids need to be unique so there must not be two services/shipments with the same id.
          example: 7fe77504-7df8-4497-843c-02d70b6490ce
          type: string
        max_time_in_vehicle:
          default: 9223372036854776000
          description: Specifies the maximum time in seconds a delivery can stay in the vehicle. Currently, it only works with services of "type":"delivery".
          example: 900
          format: int64
          type: integer
        name:
          description: Meaningful name for service, e.g. `"deliver pizza"`.
          example: delivery pizza
          type: string
        preparation_time:
          default: 0
          description: Specifies the preparation time in seconds. It can be used to model parking lot search time since if you have 3 identical locations in a row, it only falls due once.
          example: 300
          format: int64
          maximum: 604800
          minimum: 0
          type: integer
        priority:
          default: 2
          description: Specifies the priority. Can be 1 = high priority to 10 = low priority. Often there are more services/shipments than the available vehicle fleet can handle. Then you can set priorities to differentiate high priority tasks from those that could be left unassigned. I.e. the lower the priority the earlier these tasks are omitted in the solution.
          example: 1
          format: int32
          type: integer
        required_skills:
          description: 'Specifies an array of required skills, i.e. array of string (not case sensitive). For example, if this service needs to be conducted by a technician having a `drilling_machine` and a `screw_driver` then specify the array as follows: `["drilling_machine","screw_driver"]`. This means that the service can only be done by a vehicle (technician) that has the skills `drilling_machine` AND `screw_driver` in its skill array. Otherwise it remains unassigned.'
          example:
            - drilling_machine
            - screw_driver
          items:
            type: string
          type: array
        size:
          default:
            - 0
          description: Size can have multiple dimensions and should be in line with the capacity dimension array of the vehicle type. For example, if the item that needs to be delivered has two size dimension, volume and weight, then specify it as follow [ 20, 5 ] assuming a volume of 20 and a weight of 5.
          example:
            - 30
            - 5
            - 1
          items:
            format: int32
            type: integer
          type: array
        time_windows:
          description: Specifies an array of time window objects (see time_window object below). Specify the time either with the recommended Unix time stamp (the number of seconds since 1970-01-01) or you can also count the seconds relative to Monday morning 00:00 and define the whole week in seconds. For example, Monday 9am is then represented by 9hour * 3600sec/hour = 32400. In turn, Wednesday 1pm corresponds to 2day * 24hour/day * 3600sec/hour + 1day * 13hour/day * 3600sec/hour = 219600. See this tutorial for more information.
          example:
            - earliest: 32400
              latest: 36000
            - earliest: 50400
              latest: 54000
          items:
            $ref: "#/components/schemas/TimeWindow"
          type: array
        type:
          default: service
          description: Specifies type of service. This makes a difference if items are loaded or unloaded, i.e. if one of the size dimensions > 0. If it is specified as `service` or `pickup`, items are loaded and will stay in the vehicle for the rest of the route (and thus consumes capacity for the rest of the route). If it is a `delivery`, items are implicitly loaded at the beginning of the route and will stay in the route until delivery (and thus releases capacity for the rest of the route).
          enum:
            - service
            - pickup
            - delivery
          example: delivery
          type: string
      required:
        - id
      type: object
    Shipment:
      properties:
        allowed_vehicles:
          description: 'Specifies an array of allowed vehicles, i.e. array of vehicle ids. For example, if this shipment can only be conducted EITHER by "technician_peter" OR "technician_stefan" specify this as follows: ["technician_peter","technician_stefan"].'
          example:
            - technician_peter
            - technician_stefan
          items:
            type: string
          type: array
        delivery:
          $ref: "#/components/schemas/Stop"
        disallowed_vehicles:
          description: Specifies an array of disallowed vehicles, i.e. array of vehicle ids.
          example:
            - driver-A
            - driver-B
          items:
            type: string
          type: array
        id:
          description: Specifies the id of the shipment. Ids need to be unique so there must not be two services/shipments with the same id.
          example: 7fe77504-7df8-4497-843c-02d70b6490ce
          type: string
        max_time_in_vehicle:
          default: 9223372036854776000
          description: Specifies the maximum time in seconds a shipment can stay in the vehicle.
          example: 1800
          format: int64
          type: integer
        name:
          description: Meaningful name for shipment, e.g. "pickup and deliver pizza to Peter".
          example: pickup and deliver pizza to Peter
          type: string
        pickup:
          $ref: "#/components/schemas/Stop"
        priority:
          default: 2
          description: Specifies the priority. Can be 1 = high priority to 10 = low priority. Often there are more services/shipments than the available vehicle fleet can handle. Then you can set priorities to differentiate high priority tasks from those that could be left unassigned. I.e. the lower the priority the earlier these tasks are omitted in the solution.
          example: 1
          format: int32
          type: integer
        required_skills:
          description: 'Specifies an array of required skills, i.e. array of string (not case sensitive). For example, if this shipment needs to be conducted by a technician having a `drilling_machine` and a `screw_driver` then specify the array as follows: `["drilling_machine","screw_driver"]`. This means that the service can only be done by a vehicle (technician) that has the skills `drilling_machine` AND `screw_driver` in its skill array. Otherwise it remains unassigned.'
          example:
            - drilling_machine
            - screw_driver
          items:
            type: string
          type: array
        size:
          default:
            - 0
          description: Size can have multiple dimensions and should be in line with the capacity dimension array of the vehicle type. For example, if the item that needs to be delivered has two size dimension, volume and weight, then specify it as follow [ 20, 5 ] assuming a volume of 20 and a weight of 5.
          example:
            - 3
          items:
            format: int32
            type: integer
          type: array
      required:
        - id
        - pickup
        - delivery
      type: object
    SnappedWaypoint:
      description: Access point to the (road)network. It is only available if `return_snapped_waypoints` is true (be default it is false).
      properties:
        lat:
          description: Latitude of location.
          example: 51.512665
          format: double
          type: number
        lon:
          description: Longitude of location.
          example: -0.092869
          format: double
          type: number
      type: object
    Solution:
      description: Only available if status field indicates `finished`.
      properties:
        completion_time:
          description: Overall completion time in seconds, i.e. the sum of each routes/drivers operation time.
          example: 12000
          format: int64
          type: integer
        costs:
          deprecated: true
          format: int32
          type: integer
        distance:
          description: Overall distance travelled in meter, i.e. the sum of each route's transport distance
          example: 1200
          format: int32
          type: integer
        max_operation_time:
          description: Operation time of longest route in seconds.
          example: 4000
          format: int64
          type: integer
        no_unassigned:
          description: Number of jobs that could not be assigned to final solution.
          example: 1
          format: int32
          type: integer
        no_vehicles:
          description: Number of employed vehicles.
          example: 10
          format: int32
          type: integer
        preparation_time:
          description: Overall preparation time in seconds.
          format: int64
          type: integer
        routes:
          description: An array of routes
          items:
            $ref: "#/components/schemas/Route"
          type: array
        service_duration:
          description: Overall service time in seconds.
          example: 1200
          format: int64
          type: integer
        time:
          deprecated: true
          description: Use `transport_time` instead.
          format: int64
          type: integer
        transport_time:
          description: Overall time travelled in seconds, i.e. the sum of each route's transport time.
          example: 12000
          format: int64
          type: integer
        unassigned:
          properties:
            breaks:
              description: An array of ids of unassigned breaks
              items:
                description: Id of unassigned breaks
                type: string
              type: array
            details:
              description: An array of details, i.e. reason for unassigned services or shipments
              example:
                - code: 3
                  id: service-1
                  reason: does not fit into any vehicle due to capacity
                - code: 27
                  id: service-2
                  reason: could not be assigned due to max job constraint
                - code: 2
                  id: shipment-5
                  reason: cannot be visited within time window
              items:
                $ref: "#/components/schemas/Detail"
              type: array
            services:
              description: An array of ids of unassigned services
              example:
                - service-1
                - service-3
              items:
                description: Id of unassigned service
                type: string
              type: array
            shipments:
              description: An array of ids of unassigned shipments
              example:
                - shipment-5
              items:
                description: Id of unassigned shipments
                type: string
              type: array
          type: object
        waiting_time:
          description: Overall waiting time in seconds.
          example: 200
          format: int64
          type: integer
      type: object
    Stop:
      properties:
        address:
          $ref: "#/components/schemas/Address"
          description: Specifies pickup or delivery address.
        duration:
          default: 0
          description: Specifies the duration of the pickup or delivery in seconds, e.g. how long it takes unload items at the customer site.
          example: 1800
          format: int64
          maximum: 604800
          minimum: 0
          type: integer
        group:
          description: Group this stop belongs to. See the group relation and [this post](https://discuss.graphhopper.com/t/4040) on how to utilize this.
          example: ASAP
          type: string
        preparation_time:
          default: 0
          description: Specifies the preparation time in seconds. It can be used to model parking lot search time since if you have 3 identical locations in a row, it only falls due once.
          example: 300
          format: int64
          maximum: 604800
          minimum: 0
          type: integer
        time_windows:
          description: 'Specifies an array of time window objects (see time window object below). For example, if an item needs to be delivered between 7am and 10am then specify the array as follows: [ { "earliest": 25200, "latest" : 32400 } ] (starting the day from 0 in seconds).'
          example:
            - earliest: 32400
              latest: 36000
            - earliest: 50400
              latest: 54000
          items:
            $ref: "#/components/schemas/TimeWindow"
          type: array
      type: object
    SymmetricalMatrixRequest:
      example:
        out_arrays:
          - weights
          - times
          - distances
        point_hints:
          - Copenhagen Street
          - Richmond Avenue
          - White Lion Street
        points:
          - - -0.11379003524780275
            - 51.53664617804063
          - - -0.10866165161132814
            - 51.538621486960956
          - - -0.11059284210205078
            - 51.53245503603458
        vehicle: car
      properties:
        curbsides:
          description: Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap.
          items:
            type: string
          type: array
        fail_fast:
          default: true
          description: Specifies whether or not the matrix calculation should return with an error as soon as possible in case some points cannot be found or some points are not connected. If set to `false` the time/weight/distance matrix will be calculated for all valid points and contain the `null` value for all entries that could not be calculated. The `hint` field of the response will also contain additional information about what went wrong (see its documentation).
          type: boolean
        out_arrays:
          description: Specifies which matrices should be included in the response. Specify one or more of the following options `weights`, `times`, `distances`. The units of the entries of `distances` are meters, of `times` are seconds and of `weights` is arbitrary and it can differ for different vehicles or versions of this API.
          items:
            type: string
          type: array
        point_hints:
          description: Optional parameter. Specifies a hint for each point in the `points` array to prefer a certain street for the closest location lookup. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.
          items:
            type: string
          type: array
        points:
          description: "Specify multiple points for which the weight-, route-, time- or distance-matrix should be calculated as follows: `[longitude,latitude]`. In this case the origins are identical to the destinations. Thus, if there are N points, NxN entries are calculated. The order of the point parameter is important. Specify at least three points. Cannot be used together with `from_point` or `to_point.`."
          items:
            items:
              format: double
              type: number
            type: array
          type: array
        snap_preventions:
          description: Optional parameter to avoid snapping to a certain road class or road environment. Current supported values `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`
          items:
            type: string
          type: array
        turn_costs:
          default: false
          description: Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
          type: boolean
        vehicle:
          allOf:
            - $ref: "#/components/schemas/VehicleProfileId"
            - description: The vehicle profile for which the route should be calculated. Other vehicles are listed [here](#section/Map-Data-and-Routing-Profiles/OpenStreetMap) for the details.
      type: object
    TimeWindow:
      properties:
        earliest:
          default: 0
          description: Specifies the opening time of the time window in seconds, i.e. the earliest time the service can start.
          format: int64
          type: integer
        latest:
          default: 9223372036854776000
          description: Specifies the closing time of the time window in seconds, i.e. the latest time the service can start.
          format: int64
          type: integer
      type: object
    TimeWindowBreak:
      properties:
        duration:
          description: Specifies the duration of the break in seconds.
          example: 2700
          format: int64
          type: integer
        earliest:
          description: Specifies the earliest start time of the break in seconds.
          example: 1550136467
          format: int64
          type: integer
        latest:
          description: Specifies the latest start time of break in seconds.
          example: 1550148467
          format: int64
          type: integer
      required:
        - earliest
        - latest
        - duration
      type: object
    Vehicle:
      properties:
        break:
          anyOf:
            - $ref: "#/components/schemas/TimeWindowBreak"
            - $ref: "#/components/schemas/DriveTimeBreak"
        earliest_start:
          default: 0
          description: Earliest start of vehicle in seconds. It is recommended to use the unix timestamp.
          format: int64
          type: integer
        end_address:
          $ref: "#/components/schemas/Address"
          description: If this is omitted AND return_to_depot is true then the vehicle needs to return to its start_address.
        latest_end:
          default: 9223372036854776000
          description: Latest end of vehicle in seconds, i.e. the time the vehicle needs to be at its end location at latest.
          format: int64
          type: integer
        max_activities:
          description: Specifies the maximum number of activities a vehicle can conduct.
          example: 24
          format: int32
          type: integer
        max_distance:
          description: Specifies the maximum distance (in meters) a vehicle can go.
          example: 400000
          format: int64
          type: integer
        max_driving_time:
          description: Specifies the maximum drive time (in seconds) a vehicle/driver can go, i.e. the maximum time on the road (service and waiting times are not included here)
          example: 28800
          format: int64
          type: integer
        max_jobs:
          description: Specifies the maximum number of jobs a vehicle can load.
          example: 12
          format: int32
          type: integer
        min_jobs:
          description: Specifies the minimum number of jobs a vehicle should load. This is a soft constraint, i.e. if it is not possible to fulfill “min_jobs”, we will still try to get as close as possible to this constraint.
          example: 12
          format: int32
          type: integer
        move_to_end_address:
          description: Indicates whether a vehicle should be moved even though it has not been assigned any jobs.
          type: boolean
        return_to_depot:
          default: true
          description: If it is false, the algorithm decides where to end the vehicle route. It ends in one of your customers' locations. The end is chosen such that it contributes to the overall objective function, e.g. min transport_time. If it is true, you can either specify a specific end location (which is then regarded as end depot) or you can leave it and the driver returns to its start location.
          type: boolean
        skills:
          description: Array of skills, i.e. array of string (not case sensitive).
          example:
            - drilling_maschine
            - screw_driver
          items:
            type: string
          type: array
        start_address:
          $ref: "#/components/schemas/Address"
        type_id:
          default: default-type
          description: The type ID assigns a vehicle type to this vehicle. You can specify types in the array of vehicle types. If you omit the type ID, the default type is used. The default type is a `car` with a capacity of 0.
          example: my-own-type
          type: string
        vehicle_id:
          description: Specifies the ID of the vehicle. Ids must be unique, i.e. if there are two vehicles with the same ID, an error is returned.
          example: vehicle-1
          type: string
      required:
        - vehicle_id
        - start_address
      type: object
    VehicleProfileId:
      default: car
      enum:
        - car
        - bike
        - foot
        - hike
        - mtb
        - racingbike
        - scooter
        - truck
        - small_truck
      type: string
    VehicleType:
      properties:
        capacity:
          default:
            - 0
          description: Specifies an array of capacity dimension values which need to be int values. For example, if there are two dimensions such as volume and weight then it needs to be defined as [ 1000, 300 ] assuming a maximum volume of 1000 and a maximum weight of 300.
          example:
            - 100
            - 500
          items:
            format: int32
            type: integer
          type: array
        consider_traffic:
          default: false
          description: Specifies whether traffic should be considered. if "tomtom" is used and this is false, free flow travel times from "tomtom" are calculated. If this is true, historical traffic info are used. We do not yet have traffic data for "openstreetmap", thus, setting this true has no effect at all.
          type: boolean
        cost_per_activation:
          description: "**_BETA feature_**! Cost parameter vehicle activation, i.e. fixed costs per vehicle"
          format: double
          type: number
        cost_per_meter:
          description: "**_BETA feature_**! Cost parameter per distance unit, here meter is used"
          format: double
          type: number
        cost_per_second:
          description: "**_BETA feature_**! Cost parameter per time unit, here second is used"
          format: double
          type: number
        network_data_provider:
          default: openstreetmap
          description: Specifies the network data provider. Either use [`openstreetmap`](#section/Map-Data-and-Routing-Profiles/OpenStreetMap) (default) or [`tomtom`](#section/Map-Data-and-Routing-Profiles/TomTom) (add-on required).
          enum:
            - openstreetmap
            - tomtom
          type: string
        profile:
          allOf:
            - description: Specifies the vehicle profile of this type. The profile is used to determine the network, speed and other physical attributes to use for routing the vehicle.
            - $ref: "#/components/schemas/VehicleProfileId"
        service_time_factor:
          default: 1
          description: Specifies a service time factor for this vehicle type. If the vehicle/driver that uses this type is able to conduct the service as double as fast as it is determined in the corresponding service or shipment then set it to 0.5.
          format: double
          type: number
        speed_factor:
          default: 1
          description: Specifies a speed factor for this vehicle type. If the vehicle that uses this type needs to be only half as fast as what is actually calculated with our routing engine then set the speed factor to 0.5.
          format: double
          type: number
        type_id:
          description: Specifies the id of the vehicle type. If a vehicle needs to be of this type, it should refer to this with its type_id attribute.
          example: my-own-type
          type: string
      required:
        - type_id
      type: object
  securitySchemes:
    api_key:
      in: query
      name: key
      type: apiKey
