Navigation services

Navigation services allow you to build routes and receive information about the distance and travel time between points on the map, with or without consideration of traffic jams (depending on the configuration).

This article describes how to deploy and configure the Navigation services in your environment. To learn how to use the RESTful API provided by the Navigation services, see the documentation for the individual APIs (found in the top menu under "Navigation").

Architecture

The primary navigation services are the following:

• Navi-Castle - imports data from S3 storage and serves it to Navi-Back in a consumable format.
• Navi-Front - receives requests from applications and forwards them to Navi-Router and Navi-Back.
• Navi-Router - verifies the request using the API Keys service to determine if they should be processed. Then performs routing using regions and rules system: selects the appropriate Navi-Back service to process the request.
• Navi-Back - processes the request.
• Navi-Splitter - splits complex requests into parts and enables executing them in parallel on different Navi-Back instances. Used only for working with Distance Matrix API in synchronous mode.
• Navi-Attractor - attracts points to the road graph.

Additional navigation services:

• Distance Matrix Async API - calculates distance matrices for a large number of points in asynchronous mode. See the detailed scheme of services interaction in this scenario in the Processing asynchronous requests to Distance Matrix API section.
• TSP API - builds the shortest route to pass through the specified points. See the detailed scheme of services interaction in this scenario in the Solving the traveling salesman problem section.
• Restrictions API - allows you to add custom information about road closures. See the details in the Working with road closures section.
• Traffic API proxy - provides real-time traffic data from Urbi traffic servers. Navi-Back service uses this data to build routes that consider traffic conditions. See the details in the Installing Traffic API proxy instruction.

Navigation services employ a scalable architecture that allows easy distribution of incoming requests among several Navi-Back instances:

• Navi-Front automatically discovers deployed Navi-Router and Navi-Back instances by checking services' labels in the Kubernetes namespace Navi-Front resides.

• There can be several Navi-Back instances, each serving a dedicated part of requests. Consequently, these instances fetch only the required data sets from the Navi-Castle services.

  Each Navi-Back has one or several map regions it can process called a "rule". This behavior is configured by the rules file. This allows to distribute the workload and to plan the computational resources according to this file. For example, a small Navi-Back instance can process a moderate amount of requests for a certain small region, while a more performant Navi-Back instance processes a large amount of requests for a bigger region.

When Navi-Front receives an incoming request:

1. It forwards the request to the Navi-Router service.

2. Navi-Router uses the same rules files as Navi-Back, and collects all the required data from Navi-Castle. Using the rules file and the collected data, Navi-Router finds a rule under which the request falls. In other words, Navi-Router determines if there is a Navi-Back that can process the request.

   If the request is successfully validated in the API Keys service and a suitable rule exists, then Navi-Router sends the name of the rule to Navi-Front.

3. Navi-Front finds a suitable Navi-Back instance that is configured to work according to the received rule, and forwards the request to this instance.

4. The Navi-Back instance processes the request and returns a response to Navi-Front.

5. Navi-Front sends the response back to the request initiator.

---

Navigation services can be deployed in two different configurations:

• All four services. This is the recommended deployment method that ensures security, scalability, and reliability.

• All services, except for Distance Matrix Async API. This configuration is recommended if you don't need to support processing large numbers of points in Distance Matrix API.

• Only Navi-Castle and Navi-Back. In this case, all requests are processed directly by Navi-Back, and the request verification and routing steps are skipped. We recommend this configuration for testing purposes only.

  Note:

  Without Navi-Router, Navi-Back is able to process only the requests that fall under the single configured Navi-Back's rule set. In a distributed deployment, Navi-Front and Navi-Router services are required for On-Premise Navigation services to operate.

• Depending on your needs, you can also skip installing the TSP API, the Restrictions API, or the Traffic API proxy services.

Processing asynchronous requests to Distance Matrix API

To process large numbers of points using the Distance Matrix API, you need to install its asynchronous version: the Distance Matrix Async API. The service acts as a frontend for the Navi-Back service, interacting with it via an S3 compatible storage and Apache Kafka events. To determine which of the Navi-Back instances is capable of processing each particular request, Distance Matrix Async API uses data downloaded from the Navi-Castle service.

The user requests are processed asynchronously. After sending a request to Distance Matrix Async API, the user should periodically request information about its processing status. The statuses are stored in PostgreSQL.

Request processing order:

1. The user sends a request to Distance Matrix Async API in the REST or gRPC format. If gRPC requests are used, the Navi Async gRPC proxy transforms them into the REST format.

2. Distance Matrix Async API service splits the request into sub-requests and saves the data to the S3 storage.

3. Distance Matrix Async API creates an event in Apache Kafka. To determine which of the Apache Kafka topic the event must be sent to, it uses data downloaded earlier from the Navi-Castle service, as well as the rules defined in the topicRules setting.

   If the user asks for the status of the request at this point, they will receive information that the request is still being processed.

4. One of the Navi-Attractor instances reads the Apache Kafka event, loads the request data from the S3 storage, and "attracts" request points to the graph. After the work is finished, either successfully or not, Navi-Attractor creates a new Apache Kafka event by writing calculation results into the S3 storage.

5. Distance Matrix Async API reads the attraction event, gets calculation results from the S3 storage, creates a task for Navi-Back, and send the task notification to Apache Kafka.

6. One of the Navi-Back instances reads the Apache Kafka event, loads the request data from the S3 storage, and performs necessary calculations. After the work is finished, either successfully or not, Navi-Back creates a new Apache Kafka event in the topic specified in the consumerCancelTopic setting. If necessary, the calculation results are written into the S3 storage.

7. Distance Matrix Async Merger combines responses from all sub-requests into one response and saves the result to the S3 storage.

8. Distance Matrix Async API reads the Apache Kafka event and, if necessary, loads the response data from the S3 storage.

   If the user asks for the status of the request at this point, they will receive information that the request has finished processing and will receive the processing result.

In some cases, Distance Matrix Async API may cancel the processing of a request after it has been sent to Navi-Back. To do so, Distance Matrix Async API creates events in the topics specified in the consumerTaskTopic and consumerCancelTopic settings.

To communicate with other services, Distance Matrix Async API uses Apache Kafka topics as follows:

• Interaction with the Navi-Back service:

  • Distance Matrix Async API sends tasks to Navi-Back via taskTopic. The topic name is specified in the following parameters:

    • kafka.taskTopicRules.topic in the Distance Matrix Async API configuration file
    • kafka.distanceMatrix.taskTopic in the Navi-Back configuration file

  • Navi-Back sends task statuses to Distance Matrix Async API via statusTopic. The topic name is specified in the following parameters:

    • kafka.oneToManyTopic in the Distance Matrix Async API configuration file
    • kafka.distanceMatrix.statusTopic in the Navi-Back configuration file

• Interaction with the Navi-Attractor service:

  • Distance Matrix Async API sends tasks to Navi-Attractor via taskTopic. The topic name is specified in the following parameters:

    • kafka.attractTopicRules.topic in the Distance Matrix Async API configuration file
    • kafka.distanceMatrix.taskTopic in the Navi-Attractor configuration file

  • Navi-Attractor sends task statuses to Distance Matrix Async API via statusTopic. The topic name is specified in the following parameters:

    • kafka.attractTopic in the Distance Matrix Async API configuration file
    • kafka.distanceMatrix.statusTopic in the Navi-Attractor configuration file

• Task cancellation for Navi-Back and Navi-Attractor:

  Distance Matrix Async API can cancel tasks for Navi-Back and Navi-Attractor via cancelTopic (a shared topic for both services). The topic name is specified in the following parameters:

  • kafka.cancelTopic in the Distance Matrix Async API configuration file
  • kafka.distanceMatrix.cancelTopic in the Navi-Back configuration file
  • kafka.distanceMatrix.cancelTopic in the Navi-Attractor configuration file

• Interaction with the Distance Matrix Async Merger service:

  • Distance Matrix Async API sends tasks to Distance Matrix Async Merger via mergerTaskTopic. The topic name is specified in the kafka.mergerTaskTopic parameter in the Distance Matrix Async API configuration file.
  • Distance Matrix Async Merger sends task statuses to Distance Matrix Async API via mergerStatusTopic. The topic name is specified in the kafka.mergerStatusTopic parameter in the Distance Matrix Async API configuration file.

Solving the traveling salesman problem

To solve the traveling salesman problem (TSP/VRP), install the TSP API service. This service enables building the shortest route by time or distance for visiting points by one or multiple couriers. The TSP API interacts with the Distance Matrix Async API to obtain a distance matrix for all possible pairs of points and then selects the most optimal combination of these distances to solve the problem.

Request processing order:

1. The user sends a request.
2. The VRP Task Manager service saves the request data to an S3 compatible storage and records the task status in a PostgreSQL database. At this and the following stages, the user can query the task status with a separate request.
3. The VRP Task Manager service sends the Distance Matrix Async API a task to calculate a distance matrix for all points received in the request and updates the task status.
4. The Distance Matrix Async API writes the calculation result to the S3 compatible storage. The VRP Task Manager service updates the task status.
5. Based on the calculated distance matrix, the VRP Solver service computes the optimal route. The VRP Task Manager service updates the task status.
6. The VRP Solver service writes the result to the S3 compatible storage. The VRP Task Manager service updates the task status.
7. The user queries the task status, and the VRP Task Manager service returns the solution.

For more details on using the TSP API, see the documentation.

Working with road closures

You can work with road closures in only one of two ways:

• Use closure information from the provided 2GIS data. In this case, you must not install the Restrictions API.
• Install the Restrictions API and add custom closure information. In this case, only the added closures will be used to build routes. The Restrictions API service interacts with the Navi-Castle and Navi-Back services to obtain geographic data and also provides a RESTful API for working with it.

Important

Using the Restrictions API service (cron.enabled.restriction parameter) and provided data (cron.enabled.restrictionImport parameter) simultaneously in the configuration file for Navi-Castle will result in incorrect operation.

Example of a configuration file for using the provided data:

values-castle.yaml

...

cron:
  enabled:
    import: true
    restriction: false // Navi-restrictions service
    restrictionImport: true // Provided data
  schedule:
    import: 11 * * * *
    restriction: "*/5 * * * *"
    restrictionImport: "*/5 * * * *"

...

Adding a closure

To add a road closure, send a POST request to the /points endpoint.

In the request body, pass the JSON with the necessary parameters:

{
    "lat": 54.943207,
    "lon": 82.93057,
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

Where:

• lat - latitude of the road closure.
• lon - longitude of the road closure.
• start_time - date and time of the start of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
• end_time - date and time of the end of the road closure in RFC 3339 format (for example, 2020-05-15T16:52:01Z).

If the road closure is added, the response contains its UUID.

Getting active closures

To get a list of currently active road closures, send a GET request to the /restrictions endpoint.

The request will return the following information:

[
    {
        "restriction_id": "ca89008e-186b-4a97-942b-739b646b6952",
        "edge_geometry": "...",
        "start_time": "2022-03-01T12:00:00Z",
        "end_time": "2022-04-01T12:00:00Z"
    }
]

Where:

• restriction_id - UUID of the road closure.
• edge_geometry - geometry of the road closure in WKT format.
• start_time - date and time of the start of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
• end_time - date and time of the end of the road closure in RFC 3339 format (for example, 2020-05-15T16:52:01Z).

Updating a closure

To update the time of a road closure, send a PATCH request to the /restrictions/{id} endpoint, where {id} is the UUID of the road closure.

In the request body, pass the JSON with the necessary parameters:

{
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

Where:

• start_time - date and time of the start of the road closure in RFC 3339 format (for example, 2020-05-15T15:52:01Z).
• end_time - date and time of the end of the road closure in RFC 3339 format (for example, 2020-05-15T16:52:01Z).

Deleting a closure

To delete a road closure, send a DELETE request to the /restrictions/{id} endpoint, where {id} is the UUID of the road closure.

If the road closure is deleted, it will not be taken into account when building routes. All road closures deleted this way and closures with an end date less than or equal to the current date will be deleted from the database on the next cleanup cycle.

Dependencies

For more information on how to check requirements for each service, refer to the System requirements document.

• For Navi-Castle

  • Shared infrastructure:

    • Support for Kubernetes Persistent Volume and dynamic Persistent Volume Claim for storing data (optional requirement).

      Important note:

      It is highly recommended to configure Persistent Volume and Persistent Volume Claim storage features in your Kubernetes cluster.

      If no persistent volume is provided to Navi-Castle, then the data will be stored on an emptyDir volume. This means that if the Navi-Castle pod is deleted, the emptyDir volume is deleted as well and all data is lost. Launching the service will require reimporting data from the S3 storage during the pod start.

  • Services:

    • Navi-Attractor
    • Navi-Back
    • Navi-Router (for basic APIs)
    • Navi-Front (for basic APIs)
    • Navi-Splitter (for synchronous Distance Matrix API)

• For Navi-Attractor

  • Services:

    • Navi-Castle
    • Navi-Back
    • Navi-Router (for basic APIs)
    • Navi-Front (for basic APIs)
    • Navi-Splitter (for synchronous Distance Matrix API)

• For Navi-Back

  • Services:

    • License service
    • Statistics Collection service
    • Navi-Castle
    • Navi-Attractor
    • Navi-Router (for basic APIs)
    • Navi-Front (for basic APIs)
    • Navi-Splitter (for synchronous Distance Matrix API)
    • Traffic API Proxy service (optional, required only for obtaining online traffic data): the service must use Traffic Update servers that provide the data in format that is suitable for Navigation services

• For Navi-Router

  • Services:

    • API Keys service
    • Navi-Castle
    • Navi-Attractor
    • Navi-Back
    • Navi-Front
    • Navi-Splitter (for synchronous Distance Matrix API)

• For Navi-Front

  • Services:

    • Navi-Castle
    • Navi-Attractor
    • Navi-Back
    • Navi-Router
    • Navi-Splitter (for synchronous Distance Matrix API)

• For Distance Matrix Async API

  • Shared infrastructure:

    • PostgreSQL
    • S3 compatible storage
    • Apache Kafka message broker

  • Services:

    • Navi-Castle
    • Navi-Attractor
    • Navi-Back
    • Navi Async gRPC proxy (if requests to the Distance Matrix Async API are received in gRPC format)
    • Distance Matrix Async API

• For TSP API

  • Shared infrastructure:

    • PostgreSQL
    • S3 compatible storage
    • Apache Kafka message broker

  • Services:

    • API Keys service
    • Navi-Castle
    • Navi-Attractor
    • Navi-Back
    • VRP Task Manager
    • VRP Solver
    • Distance Matrix Async API

• For Restrictions API

  • Shared infrastructure:

    • PostgreSQL with enabled PL/pgSQL for storing road closure data

  • Services:

    • API Keys service
    • Navi-Castle
    • Navi-Attractor
    • Navi-Back
    • Navi-Restrictions

What's next?

• Find out how to install or update the services:

  • Installing navigation API
  • Updating navigation API

• Read more about On-Premise:

  • Solution architecture
  • System requirements