Integration architecture options

When choosing an integration architecture and designing tracking system customizations, keep the following in mind:

1. Planning and Track & Trace are different services. They are independent of each other. Even if your data is already available in the Planning service, you may not necessarily be able to use them in Track & Trace (and vice versa).
2. When calling the Planning API, all data on references, settings, and previously planned routes must be stored on the tracking system side.
3. The Planning service solves problems independently, so the data required to solve a problem must be passed in the request each time. For example, with additional planning.

You can upload data to or download data from a service via Excel or the API. You can open a planning task from the RouteQ interface and export it to Track & Trace.

Support for unique order numbers in Track & Trace is an important feature of all the integration architectures. If you need to postpone a scheduled order until the following day, add a prefix to the order number when re-submitting the order to Planning (for manual export).

Basic integration with RouteQ services

When you load data via Excel, the built-in geocoder is used. It automatically finds the coordinates for the addresses you have uploaded.

API requests are not processed through the geocoder. When using the API, you need to pass location coordinates rather than addresses. Therefore, you must geocode in advance on the side of the tracking system.

If the location list does not change, you can enter location coordinates in a look-up table for later use. If delivery addresses change regularly, you need additional integration with a geocoder.

With geocoding, the address must be accurate. You're more likely to get inaccurate coordinates if:

• The address is unstructured: it's stored as a a single address line and doesn't provide enough information (the placename is very common, but the region or city district isn't specified, or the street name is given without the city name) or the information is irrelevant for determining coordinates (for example, both the apartment and the intercom number are indicated).
• The address line contains additional information, like phone numbers and comments.

We recommend the following:

• Enable search suggestions and address verification during input (for example, for customers on the website and managers that place orders);
• Separate the boxes for entering addresses, contact details, and comments on the side of the tracking system. This way, the geocoder only receives an address string with enough data necessary to determine the coordinates: the region, city, street, and building number.
• To limit the coordinate search area, use the geocoder parameter bbox.
• When you receive a response from the geocoder, use the precision tag value to precisely determine the building. If the precision isn't equal to exact or number, inform the user that they need to provide a precise address.

When to use this method

This integration method is a good choice for quickly rolling out the service to production or for a pilot implementation using small amounts of data.

We don't recommend using this integration method for tasks that require additional planning or where implementation will require a large number of manual steps.

Diagram

Implementing integration

1. Download an Excel file from the tracking system in the required format.

2. Upload the resulting file to the Planning web interface and run the task. The addresses in the file will be geocoded automatically.

3. If necessary, edit the solution in the web interface.

4. Take the result from step 3 (with your edits) and upload it to Excel. As an option, you can upload a file to the tracking system to get information on scheduled routes.

5. Take the result from step 3 and export it to Track & Trace.

6. When the couriers are done, job performance data can be saved in Excel or uploaded to the tracking system for internal reports.

When to use this method

This integration method is suitable for most tasks. It can be used as an intermediate solution prior to full API integration.

Diagram

Implementing integration

1. Before launching the task, the tracking system sends addresses to be geocoded. The geocoder returns coordinates and an accuracy flag.

2. If the coordinates are not accurate enough, adjust them manually.

3. After receiving the coordinates, the tracking system sends a request to add the task, which launches the planning process.

   The service must return one of the following responses:

   • Code for successful task queuing and task ID.

   • Error code.

   Planning time depends on the number of locations in a request. The tracking system sometimes requests information about the task status.

   Tip.

   At this stage, you can open the solution at https://yandex.ru/courier/companies/<company_id>/depots/all/mvrp/<task_id>, where:

   • <company_id>: Company ID. You can find it in Settings → Company → Company ID.

   • <task_id>: Task ID.

4. If necessary, edit the solution in the web interface.

5. The final task ID depends on whether a task has been updated:

   • If a solution has not been updated, routing information is available based on the original task ID.

   • If a solution is edited, its task ID will change. To get information about the adjusted solution, use the API.

6. Take the result from step 4 and export it to Track & Trace.

7. When the couriers are done, job performance data can be saved in Excel.

When to use this method

This integration method is suitable when you need maximum flexibility or when you need to eliminate manual operations. This option assumes that planned routes must be stored on the side of the tracking system.

Diagram

Implementing integration

1. Before launching the task, the tracking system sends addresses to be geocoded. The geocoder returns coordinates and an accuracy flag.

2. If the coordinates are not accurate enough, adjust them manually.

3. After receiving the coordinates, the tracking system sends a request to add the task, which launches the planning process.

   The service must return one of the following responses:

   • Code for successful task queuing and task ID.

   • Error code.

   Planning time depends on the number of locations in a request. The tracking system sometimes requests information about the task status.

   Tip.

   At this stage, you can open the solution at https://yandex.ru/courier/companies/<company_id>/depots/all/mvrp/<task_id>, where:

   • <company_id>: Company ID. You can find it in Settings → Company → Company ID.

   • <task_id>: Task ID.

4. If necessary, edit the solution in the web interface.

5. The final task ID depends on whether a task has been updated:

   • If a solution has not been updated, routing information is available based on the original task ID.

   • If a solution is edited, its task ID will change. To get information about the adjusted solution, use the API.

6. Save the planned routes on the tracking system side. In certain cases, you can plan without assigning a specific courier.

   After receiving data on planned routes, you can assign specific couriers on the side of the tracking system. This will be useful if:

   • Your couriers' exact schedule is unknown for the moment.

   • Ground transportation is used.

7. After assigning specific couriers, send route data to Track & Trace using the Track & Trace API. Consider the API features when you update the following data:

   • Depots.

   • Couriers and their phone numbers.

   • Routes.

   • Orders

8. Track & Trace can provide the following information after couriers have completed their tasks or while they are working:

   • Information about orders for a specific date.

   • Information about current order status.

   • Order notifications.

   • Information about the delivery quality.

When to use this method

This integration method is suitable when information on some orders is available in advance, but others continue coming in until the couriers leave. This will require new orders to be included in previously planned routes.

Note

• The tracking system must store planned route data.

• The frequency and interval of additional planning depend on the specific business model.

Diagram

Implementing integration

1. The tracking system sends a task for initial planning using the Planning API and receives the result.

2. Save the resulting solution in the tracking system to use built routes for additional planning. In the meantime, new orders accumulate.

3. The tracking system sends a task for additional planning using the Planning API. Among other things, the tracking system must pass on:

   • Order data from the initial plan and previous additional planning.

   • Bindings between orders and vehicles based on previous additional planning (not to modify previously created routes).

   • New order data.

4. Save the new planned routes on the side of the tracking system for subsequent iterations of additional planning. In the meantime, new orders continue to accumulate.

5. Repeat Steps 3 and 4 as many times as necessary until you get the final version of the solution.

6. The tracking system sends the final version of the routes via the Track & Trace API.

When to use this method

This integration method is a good choice when couriers are already on their planned routes but new orders continue coming in during their work shift.

Note

• The tracking system must store planned route data.

• The frequency and interval of additional planning depend on the specific business model.

• The planning service uses current vehicle location data. Normally, data on the most recent completed order is sufficient.

Diagram

Implementing integration

1. The tracking system sends a task for initial planning using the Planning API and receives the result.

2. Save the resulting solution in the tracking system to use for additional planning. In the meantime, new orders accumulate.

3. Information about routes is sent via the Track & Trace API.

4. In the meantime, the tracking system accumulates new orders to be added to the current plan. By this time, the couriers are already en route.

5. The Track & Trace service returns information on completed orders to the tracking system, including completion time for the most recent one (this can be a location in time in the past).

6. The tracking system sends a task for additional planning using the Planning API. A task must include:

   • Bindings between orders and vehicles based on previous additional planning (not to modify previously created routes).

   • The most recent completed order if it is used to determine vehicle location.

   • Other completed orders if they are pickup to be taken into account to calculate capacity.

   • A sequence of the next few orders if couriers are following the planned order delivery sequence.

7. Save the new planned routes on the side of the tracking system for subsequent iterations of additional planning. In the meantime, new orders continue to accumulate.

8. The tracking system updates route information via the Track & Trace API. Repeat Steps 6 and 7 as many times as necessary until you get the final version of the solution.

Example sequence of the next few orders

A courier was delivering orders 1 through 5 when a new order number 6 came in. During additional planning, orders 1 through 3 have already been completed, so the additional planning request must contain information about order 3 (this being the vehicle starting location) and orders 4 through 6.

You also need:

• To bind orders 3 through 5 to the courier since they were previously assigned to them.

• To set orders 3 and 4 to be at the start of the route because the courier was already en route to order 4 at the time of additional planning.

This way, the courier will be able to deliver order 4, and the service will find an optimized sequence to complete orders 5 and 6.

When to use this method

This integration method makes it easier for couriers to use the Yandex Courier app.

Note

• The courier's phone number and username must match and be formated as +1xxxxxxxxxx.
• If the courier is registered in multiple companies, they'll be asked to select one.
• If the courier has multiple routes planned for today, they'll be asked to select one.

Implementing integration

1. Add the phone numbers of couriers who need to use the Yandex Courier app via the Logistician's workspace or the API.
2. Plan routes:

   • Via Excel: Enter the courier's phone number in the Courier ID and Courier's phone number fields.

     For phone numbers with the + symbol to be uploaded to Track & Trace correctly, enter the ' (single quote) symbol before the plus.

     
   • Via the API: Enter the courier's phone number in the vehicles.id and vehicles.phone fields.
3. Take the result from step 2 and export it to Track & Trace.

As a result, the courier won't have to enter their username to use the app.

Contact support