---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.kz/routing/doc/en/vrp/add-task.md
  - https://yandex.kz/routing/doc/kk/vrp/add-task.md
  - https://yandex.kz/routing/doc/ru/vrp/add-task.md
  - href: en/vrp/add-task.md
    type: text/markdown
    title: Markdown version
  - href: llms.txt
    type: text/markdown
    title: llms.txt
title: RouteQ — integration with the API — request structure
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.kz/routing/doc/en/llms.txt


# Adding a task

When using the API to plan routes, the parameters are passed to RouteQ in the request body in JSON format. You can queue a task for processing using the `/add/mvrp` method. To learn more, see [specifications](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/addMVRPTask).

To get a task execution result in your preferred language, add the `lang` parameter at the end of the task creation request. This parameter specifies the language for all response fields, including the reasons for unallocated orders. Acceptable values:

- `ru` — Russian
- `en` — English

**Sample requests**:

{% list tabs %}

- With an API key
  
  <!-- source: en/vrp/_includes/example-api-key.md -->
  ```bash
  curl -H "Content-Type: application/json" -X POST -d <request-body> https://courier.yandex.ru/vrs/api/v1/add/mvrp?apikey=<your-API-key>&lang=en
  ```
  <!-- endsource: en/vrp/_includes/example-api-key.md -->

- With an OAuth token

  <!-- source: en/vrp/_includes/example-oauth-token.md -->
  ```bash
  curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X POST -d <request-body> https://courier.yandex.ru/api/v1/vrs/add/mvrp?lang=en
  ```
  <!-- endsource: en/vrp/_includes/example-oauth-token.md -->

{% endlist %}

<!-- source: en/_includes/postman-collection.md -->
To send API requests, you can use the [Routing API](https://doc-static.yandex.net/src/dev/routing/postman-collection/routeq-api-postman-collection-en.zip) collection. To learn how to import the collection into Postman or Bruno, see [Working with an existing request collection](https://yandex.kz/routing/doc/en/vrp/upload-api-collection.md).
<!-- endsource: en/_includes/postman-collection.md -->

## Description of the request body {#request-structure}

{% cut "JSON structure" %} 

```json
{
    "depot": {
        // Describes the depot (if it's the only depot).
    },
    "depots": [
        // Describes depots (if there are multiple depots).
    ],
    "locations": [
        // Describes orders.
    ],
    "vehicles": [
        // Describes vehicles.
        "planned_route": {
            // Describes previously planned destinations without specifying the visit sequence.
        }
    ],
   "options": {
        // Describes routing options.
        "incompatible_load_types": [
            // Describes incompatible order types.
         ],
        "location_groups": [
            // Describes order groups.
           ]
     },
    "zones": [
        // Describes geofences (if geofences from the interface aren't used).
    ]
}
```

{% endcut %}

#|
||**Object/array** | **Description** | **Compliance with Excel sheets** | **Required** ||
||`depot`
`depots` | [Depot](https://yandex.kz/routing/doc/en/vrp/properties-of-depot.md)
**Depot** and **Depots** are mutually exclusive objects. You can only use one of them at a time. | [Depot or Depots](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#depot-depots) | <!-- diplodoc:svg ![](_images/check.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 13.00" width="16.00" height="13.00"><path fill="#fece06" d="   M 14.06 0.00   L 16.00 0.00   L 16.00 1.81   L 6.69 13.00   L 4.94 13.00   L 0.00 7.44   L 0.00 5.94   C 2.21 3.92 4.10 7.71 5.56 9.07   Q 5.97 9.45 6.33 9.02   L 14.06 0.00   Z"/></svg>||
||`locations` | [Order](https://yandex.kz/routing/doc/en/vrp/properties-of-orders.md) | [Orders](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#orders) | <!-- diplodoc:svg ![](_images/check.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 13.00" width="16.00" height="13.00"><path fill="#fece06" d="   M 14.06 0.00   L 16.00 0.00   L 16.00 1.81   L 6.69 13.00   L 4.94 13.00   L 0.00 7.44   L 0.00 5.94   C 2.21 3.92 4.10 7.71 5.56 9.07   Q 5.97 9.45 6.33 9.02   L 14.06 0.00   Z"/></svg>||
||`vehicles` | [Vehicle](https://yandex.kz/routing/doc/en/vrp/properties-of-vehicles.md) | [Vehicles](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#vehicles) | <!-- diplodoc:svg ![](_images/check.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 13.00" width="16.00" height="13.00"><path fill="#fece06" d="   M 14.06 0.00   L 16.00 0.00   L 16.00 1.81   L 6.69 13.00   L 4.94 13.00   L 0.00 7.44   L 0.00 5.94   C 2.21 3.92 4.10 7.71 5.56 9.07   Q 5.97 9.45 6.33 9.02   L 14.06 0.00   Z"/></svg>||
||`planned_route` | [Planned route](https://yandex.kz/routing/doc/en/vrp/properties-of-vehicles-routes.md#planned-route) | [Routes](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#routes) | <!-- diplodoc:svg ![](_images/cross.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 16.00" width="16.00" height="16.00"><path fill="#ababab" d="   M 0.00 0.00   L 2.81 0.00   L 7.71 4.94   Q 8.15 5.39 8.56 4.90   Q 10.95 2.03 14.06 0.00   L 16.00 0.00   L 16.00 2.56   L 11.03 7.70   Q 10.64 8.12 11.04 8.52   L 16.00 13.56   L 16.00 16.00   L 13.44 16.00   L 8.46 11.21   Q 8.00 10.76 7.52 11.20   L 2.44 16.00   L 0.00 16.00   L 0.00 13.94   L 4.95 8.44   Q 5.33 8.02 4.94 7.62   L 0.00 2.44   L 0.00 0.00   Z"/></svg>||
||`options` | [Routing options](https://yandex.kz/routing/doc/en/vrp/routing-options_index-page.md) | [Options](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#options) | <!-- diplodoc:svg ![](_images/check.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 13.00" width="16.00" height="13.00"><path fill="#fece06" d="   M 14.06 0.00   L 16.00 0.00   L 16.00 1.81   L 6.69 13.00   L 4.94 13.00   L 0.00 7.44   L 0.00 5.94   C 2.21 3.92 4.10 7.71 5.56 9.07   Q 5.97 9.45 6.33 9.02   L 14.06 0.00   Z"/></svg>||
||`incompatible_load_types` | [Order incompatibility](https://yandex.kz/routing/doc/en/vrp/properties-of-orders.md) | [Incompatible_order_types](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#incompatible-order-types) | <!-- diplodoc:svg ![](_images/cross.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 16.00" width="16.00" height="16.00"><path fill="#ababab" d="   M 0.00 0.00   L 2.81 0.00   L 7.71 4.94   Q 8.15 5.39 8.56 4.90   Q 10.95 2.03 14.06 0.00   L 16.00 0.00   L 16.00 2.56   L 11.03 7.70   Q 10.64 8.12 11.04 8.52   L 16.00 13.56   L 16.00 16.00   L 13.44 16.00   L 8.46 11.21   Q 8.00 10.76 7.52 11.20   L 2.44 16.00   L 0.00 16.00   L 0.00 13.94   L 4.95 8.44   Q 5.33 8.02 4.94 7.62   L 0.00 2.44   L 0.00 0.00   Z"/></svg>||
||`location_groups` | [Order grouping](https://yandex.kz/routing/doc/en/vrp/grouping-locations.md) | [Location_groups](https://yandex.kz/routing/doc/en/vrp/excel-fill-guide.md#location-groups) | <!-- diplodoc:svg ![](_images/cross.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 16.00" width="16.00" height="16.00"><path fill="#ababab" d="   M 0.00 0.00   L 2.81 0.00   L 7.71 4.94   Q 8.15 5.39 8.56 4.90   Q 10.95 2.03 14.06 0.00   L 16.00 0.00   L 16.00 2.56   L 11.03 7.70   Q 10.64 8.12 11.04 8.52   L 16.00 13.56   L 16.00 16.00   L 13.44 16.00   L 8.46 11.21   Q 8.00 10.76 7.52 11.20   L 2.44 16.00   L 0.00 16.00   L 0.00 13.94   L 4.95 8.44   Q 5.33 8.02 4.94 7.62   L 0.00 2.44   L 0.00 0.00   Z"/></svg>||
||`zones` | [Geofences](https://yandex.kz/routing/doc/en/vrp/geozones.md) | - | <!-- diplodoc:svg ![](_images/cross.svg) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0.00 0.00 16.00 16.00" width="16.00" height="16.00"><path fill="#ababab" d="   M 0.00 0.00   L 2.81 0.00   L 7.71 4.94   Q 8.15 5.39 8.56 4.90   Q 10.95 2.03 14.06 0.00   L 16.00 0.00   L 16.00 2.56   L 11.03 7.70   Q 10.64 8.12 11.04 8.52   L 16.00 13.56   L 16.00 16.00   L 13.44 16.00   L 8.46 11.21   Q 8.00 10.76 7.52 11.20   L 2.44 16.00   L 0.00 16.00   L 0.00 13.94   L 4.95 8.44   Q 5.33 8.02 4.94 7.62   L 0.00 2.44   L 0.00 0.00   Z"/></svg>||
|#

\* Mandatory objects/arrays of objects when using the API to plan routes. Doesn't apply to the corresponding Excel sheets.


{% note info %}

Objects in the request body may reference your [presets](https://yandex.kz/routing/doc/en/vrp/presets.md) (predefined settings).

{% endnote %}

Minimum set of parameters for each object:

- Depots `depots`:

    - Identifier `id`.
    - Coordinates `point.lat` and `point.lon`.
    - Time window `time_window` or multiple time windows `time_windows` if the depot operates with breaks.

- Orders `locations`:

    - Identifier `id`.
    - Coordinates `point.lat` and `point.lon`.
    - Time window for completing an order `time_window` or multiple time windows `time_windows`.
    - Strictness of time window `hard_window`.
    - Order handling time (time to complete an order) `service_duration_s`.

- Couriers and vehicles `vehicles`:

    - Identifier `id`.
    - Transportation method (on foot, public transport, car, or truck) `routing_mode`.
    - Requirement to return to the depot after completing the route `return_to_depot`.

- Parameters of the planning algorithm `options`:

    - Time zone `time_zone`.

## Stopping a task {#stop-planning}

To stop a planning task that's still in progress, send a request using the [/cancel/mvrp](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/postMVRPTaskCancel) method.

In the request, specify:

* `id`: Task ID.
* `apikey`: The API key specified in the company settings. For more information about API keys, see [API key](https://yandex.kz/routing/doc/en/vrp/authorization.md#api-key).

**Request:**

```
curl -X POST https://courier.yandex.ru/vrs/api/v1/cancel/mvrp/{task-id}?apikey=<company-API-key> -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>"
```

<!-- source: en/vrp/_includes/feedback.md -->
<a href="feedback">
  <span class="button">Contact support</span>
</a>


<!-- endsource: en/vrp/_includes/feedback.md -->