Setting routes for the day

You can see the diagram showing the process of importing planning results to Track & Trace here.

At the beginning of each work day, the delivery company must upload information about routes and orders to the Track & Trace database. The generated route is automatically sent to the Yandex Courier app. The order sequence in the route is optimized based on delivery windows and the traffic forecast.

Note

Use your company ID to access the Track & Trace API. If you don't have an ID, contact us.

Building routes

In the API, routes are assigned to couriers for a specific date.

Send a request to the resource routes-batch. The request must contain information about the orders.

To send API requests via Postman, you can use the RouteQ API collection.

Alert

The specification contains required fields for existing objects, but there are more fields for new objects. When you add new objects by sending a request to the routes-batch resource, fill in all of the requires fields for the routes resource.

Request:

Windows

MacOS/Linux

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X POST -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes-batch

File

[
  {
    "courier_number":"222",
    "number":"23423-2000",
    "date": "2017-08-08",
    "depot_number":"111"
  },
  {
    "courier_number":"224",
    "number":"23423-2001",
    "date": "2017-08-08",
    "depot_number":"112"
  }
]

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -X POST -d '[{"courier_number":"222", "number":"23423-2000", "date": "2017-08-08", "depot_number":"111"}, {"courier_number":"224", "number":"23423-2001", "date": "2017-08-08", "depot_number":"112"}]' https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes-batch

Result:

{
  "inserted": 2,
  "updated": 0
}

Adding orders to the database

Orders in the API are assigned to a route. Orders on the route are arranged in the order they were added. If necessary, you can change their sequence by sending a request to the orders-sequence resource.

Send a request to the orders-batch resource. The request must contain information about the orders.

Alert

The specification contains required fields for existing objects, but there are more fields for new objects. When you add new objects by sending a request to the orders-batch resource, fill in all of the fields that are required for the orders resource.

Request:

Windows

MacOS/Linux

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X POST -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/orders-batch

File

[
  {
    "number":"222239",
    "route_number":"23423-2000",
    "address":"476 5th Avenue",
    "lat": 73.9823,
    "lon": 40.7532,
    "customer_name": "Mark",
    "phone": "+15551234567",
    "status":"new",
    "time_interval":"11-12"
  },
  {
    "number":"222241",
    "route_number":"23423-2001",
    "address":"477 5th Avenue",
    "lat": 73.9824,
    "lon": 40.7533,
    "customer_name": "Sarah",
    "phone": "+15551234568",
    "status":"new",
    "time_interval":"10:00 - 11:00"
  }
]

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -X POST -d '[{"number":"222239", "route_number":"23423-2000", "address":"476 5th Avenue", "lat": 73.9823, "lon": 40.7532, "customer_name": "Mark", "phone": "+15551234567", "status":"new", "time_interval":"11-12"}, {"number":"222241", "route_number":"23423-2001", "address":"477 5th Avenue", "lat": 73.9824, "lon": 40.7533, "customer_name": "Sarah", "phone": "+15551234568", "status":"new", "time_interval":"10:00 - 11:00"}]' https://courier.yandex.ru/api/v1/companies/<your-company-id>/orders-batch

Result:

{
  "inserted": 2,
  "updated": 0
}

To specify where an order needs to be picked up or delivered, assign that order to a depot or to another order by sending a request to the nodes resource. You can assign orders only using the API.

To send API requests via Postman, you can use the RouteQ API collection.

Specify the orders to be assigned in the value.related_orders array.

The following assignment types are possible:

pickup orders will be delivered to the depot. For the depot, specify number = <pickup order number> and action = delivery.
delivery orders will be picked up from the depot (for delivery to the drop_off point). For the depot, specify number = <delivery order number> and action = pickup.
delivery orders will be picked up from the pickup point. For the pickup order, specify number = <delivery order number> and action = pickup.
pickup orders will be delivered to the drop-off point. For the drop_off order, specify number = <pickup order number> and action = delivery.

Warning

You can only assign orders with the specified pickup, delivery or drop_off type.

Request:

Windows

MacOS/Linux

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -X POST "https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes/<route-id>/nodes"

File

[
  {
      "type": "depot",
      "value": {
          "number": "200",
          "related_orders": [
              {
                  "number": "20 2024-03-26",
                  "action": "pickup"
              }
          ]
      }
  },
  {
      "type": "depot",
      "value": {
          "number": "100",
          "related_orders": [
              {
                  "number": "19 2024-03-26",
                  "action": "pickup"
              }
          ]
      }
  },
  {
      "type": "order",
      "value": {
          "address": "United States, Huntington Station, East Jericho Turnpike, 901",
          "lat": 40.836506,
          "lon": -73.385683,
          "number": "19 2024-03-26",
          "time_interval": "08:00:00-23:00:00"
      }
  },
  {
      "type": "order",
      "value": {
          "address": "United States of America, Connecticut, Fairfield County, Bridgeport",
          "lat": 41.177449,
          "lon": -73.230018,
          "number": "20 2024-03-26",
          "time_interval": "08:00:00-23:00:00"
      }
  },
  {
      "type": "order",
      "value": {
          "address": "United States, Brooklyn, 1225 Broadway",
          "lat": 40.691776,
          "lon": -73.926379,
          "number": "21 2024-03-26",
          "time_interval": "08:00:00-23:00:00",
          "type": "pickup",
          "related_orders": [
              {
                  "number": "22 2024-03-26",
                  "action": "pickup"
              }
          ]
      }
  },
  {
      "type": "order",
      "value": {
          "address": "United States of America, New York, New York, Fort-Gamilton-Parkuey",
          "lat": 40.633057,
          "lon": -74.005327,
          "number": "22 2024-03-26",
          "time_interval": "08:00:00-23:00:00",
          "type": "delivery"
      }
  }
]

cURL

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -X POST -d '[{"type":"depot","value":{"number":"200","related_orders":[{"number":"20 2024-03-26","action":"pickup"}]}},{"type":"depot","value":{"number":"100","related_orders":[{"number":"19 2024-03-26","action":"pickup"}]}},{"type":"order","value":{"address":"United States, Huntington Station, East Jericho Turnpike, 901","lat":40.836506,"lon":-73.385683,"number":"19 2024-03-26","time_interval":"08:00:00-23:00:00"}},{"type":"order","value":{"address":"United States of America, Connecticut, Fairfield County, Bridgeport","lat":41.177449,"lon":-73.230018,"number":"20 2024-03-26","time_interval":"08:00:00-23:00:00"}},{"type":"order","value":{"address":"United States, Brooklyn, 1225 Broadway","lat":40.691776,"lon":-73.926379,"number":"21 2024-03-26","time_interval":"08:00:00-23:00:00","type":"pickup","related_orders":[{"number":"22 2024-03-26","action":"pickup"}]}},{"type":"order","value":{"address":"United States of America, New York, New York, Fort-Gamilton-Parkuey","lat":40.633057,"lon":-74.005327,"number":"22 2024-03-26","time_interval":"08:00:00-23:00:00","type":"delivery"}}]' "https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes/<route-id>/nodes"

Result:

{}

To see current assignments of orders to depots and other orders, send a request to the route-info resource.

Verifying uploaded data

To check if data was uploaded successfully, send a request to the verification resource. The server response contains information about all orders for the specified date. You can compare the information you receive with the information in the delivery company's database.

Request:

curl -H "Authorization: OAuth <your-OAuth-token>" -X GET https://courier.yandex.ru/api/v1/companies/<your-company-id>/verification?date=2018-01-01

Result:

[
  {
    "order_id": "20170513-713",
    "time_interval": "12-23",
    "route_number": "23423-2000",
    "courier_id": "your-courier-number",
    "status": "finished",
    "phone": "+155512345678",
    "address":"476 5th Avenue",
    "lat": 73.9823,
    "lon": 40.7532
  },
  {
    "order_id": "20170513-329",
    "time_interval": "12-52",
    "route_number": "23423-2001",
    "courier_id": "8272",
    "status": "finished",
    "phone": "+155512345679",
    "address":"477 5th Avenue",
    "lat": 73.9824,
    "lon": 40.7533
  }
]

Contact support

Setting routes for the day

Building routes

Adding orders to the database

Assigning orders to a depot or to another order

Verifying uploaded data

Was the article helpful?