Courier breaks

You can set courier breaks during route planning, after the route has been exported to Track & Trace, and even when the courier is already en route. Breaks aren't displayed on the map, but are considered when ETA is calculated.

Add a break

To add breaks to the courier's route, send a POST request to the work_breaks resource.

In the request, specify company_id and route_id.

In the request body, specify:

• rest_duration_s: Break duration in seconds (the minimum value is 1).
• work_time_range_till_rest: Working hours before break, in the following format: [D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]].

Query

cURL

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

File

 {
   "work_time_range_till_rest": "01:00:00-01:30:00",
   "rest_duration_s": 3600
  },{
   "work_time_range_till_rest": "02:30:00-03:00:00",
   "rest_duration_s": 1800
  }

Result

 {
  "break_id": 1,
  "sequence_pos": 0,
  "work_time_range_till_rest": "01:00:00 - 01:30:00",
  "rest_duration_s": 1800
 },
{
  "break_id": 2,
  "sequence_pos": 1,
  "work_time_range_till_rest": "02:30:00 - 03:00:00",
  "rest_duration_s": 1800
 }

Get break information

To get information about courier breaks on the route, send a GET request to the resource work_breaks. The following break statuses are available:

• planned
• started
• finished

Query

cURL

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

Result

    {
        "id": 1,
        "sequence_pos": 0,
        "work_time_range_till_rest": "01:00:00 - 01:30:00",
        "rest_duration_s": 3600,
        "status": "planned",
        "start_at": 1769743980
    },
    {
        "id": 2,
        "sequence_pos": 1,
        "work_time_range_till_rest": "02:30:00 - 03:00:00",
        "rest_duration_s": 1800,
        "status": "planned",
        "start_at": 1769802180
    }

Delete a break

To delete a break, send a DELETE request to the resource work_breaks.

Query

cURL

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

Result

{
    "id": 1,
    "sequence_pos": 0
}

Possible business case

Objective

You need to add several breaks for a courier after they've started moving along the route and track how this affects the estimated arrival time (estimated_service_time) for the orders.

Implementation

1. To get up-to-date information about the route, send a request to the route-info resource. For order id = 410522528, the ETA is 16:38.

   Sample request

   cURL

   curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X GET -d https://courier.yandex.ru/api/v1/companies/<your-company-id>/route-info?route_id=<route-id>
   

2. Schedule two 10-minute breaks:

   • First break is no later than after 40 minutes of work.
   • Second break is no later than after 70 minutes of work.

   To do this, send a request to the work_breaks resource and set the working hours before a break and the duration of breaks (in seconds).

   Sample request

   {
       "work_time_range_till_rest": "00:30:00-00:40:00",
       "rest_duration_s": 600
   },{
       "work_time_range_till_rest": "01:00:00-01:10:00",
       "rest_duration_s": 600
   }
   
   Sample response

   {
       "id": 4974223,
       "sequence_pos": 0
   },{
       "id": 4974224,
       "sequence_pos": 1
   }
   

3. To see how the estimated time of arrival has changed, resend the request to the route-info resource. For order id = 410522528, the new ETA is 16:50 (the order will be delivered after the break).

4. To check the current status of breaks, send a request to the work_breaks resource.

   Sample response

   {
       "id": 4974223,
       "sequence_pos": 0,
       "work_time_range_till_rest": "00:30:00 - 00:40:00",
       "rest_duration_s": 600,
       "status": "started",
       "start_at": 1770039360
   },{
       "id": 4974224,
       "sequence_pos": 1,
       "work_time_range_till_rest": "01:00:00 - 01:10:00",
       "rest_duration_s": 600,
       "status": "planned",
       "start_at": 1770044160
   }