Navigation API | On‑Premise | Urbi Documentation
Maps
Search
Navigation
Urbi Pro
CityLens
Account
On‑Premise

Navigation services

Navigation services allow building routes and getting information about travel time and distance between points on the map, with or without consideration of current traffic conditions.

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

On-Premise Navigation services 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.

Additional navigation services:

  • Restrictions API - provides information about road closures.
  • Traffic API proxy - provides real-time traffic data from Traffic Servers. Navi-Back service uses this data to build routes that consider traffic conditions.
  • TSP API - enables solving the traveling salesman problem (building the shortest route to pass through the specified points).

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 Restrictions API, TSP 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.

Architecture of services processing asynchronous requests

Request processing order:

  1. The user sends a request to Distance Matrix Async API.

  2. Distance Matrix Async API service splits the request into sub-requests. The splitting is done if the size of the incoming distance matrix is larger than the threshold set in the dm.taskSplitSize parameter in the Distance Matrix Async API configuration file.

  3. Distance Matrix Async API saves the data to the S3 storage.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

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

  9. 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.

Architecture of On-Premise services for solving the VRP/TSP

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 Restrictions API

Restrictions API service allows you to manage information about road closures: get a list of currently active road closures, add new road closures, and remove the ones that are no longer relevant. All road closures added via Restrictions API will be taken into account when building routes.

Restrictions API service publishes a RESTful API for use by a client application.

Restrictions API service integrates with services (Navi-Castle and Navi-Back) to obtain geographic data. Among other things, this integration includes a cron job to periodically (once per hour) retrieve current road closure information from the Navi-Castle service.

On-Premise Restrictions API service architecture

Adding road closure

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

The body of the request must contain a JSON object with the following attributes:

  • 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-15T15:52:01Z).
{
    "lat": 54.943207,
    "lon": 82.93057,
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

If the road closure was successfully added, the response will contain a UUID that can be used to update the road closure or delete it from the database.

Getting active road 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 - 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-15T15:52:01Z).
[
    {
        "restriction_id": "ca89008e-186b-4a97-942b-739b646b6952",
        "edge_geometry": "...",
        "start_time": "2022-03-01T12:00:00Z",
        "end_time": "2022-04-01T12:00:00Z"
    }
]

Updating road 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.

The body of the request must contain a JSON object with the following attributes:

  • 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-15T15:52:01Z).
{
    "start_time": "2022-03-01T12:00:00Z",
    "end_time": "2022-04-01T12:00:00Z"
}

Deleting road closure

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

On a successful request, the road closure will be marked as removed and no longer will be taken into account when building routes. All road closures marked this way as well as 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.

  • For Navi-Back

    • Services:

      • Traffic Proxy service configured to use Traffic Update servers that provide the data in format that is suitable for Navigation services.
      • Navi-Castle
      • License service
      • API Keys service

  • For Navi-Router

    • Services:

      • Navi-Castle

  • For Navi-Front

    • Services:

      • Navi-Castle
      • Navi-Router
      • Navi-Back

  • For Distance Matrix Async API

    • Shared infrastructure:

      • PostgreSQL storage
      • S3 storage
      • Apache Kafka message broker

    • Services:

      • Navi-Castle
      • Navi-Back

  • For Restrictions API

    • Shared infrastructure:

      • PostgreSQL data storage for storing road closure data. It is required to deploy PostgreSQL with PL/pgSQL enabled.

    • Services:

      • Navi-Castle
      • Navi-Back

What's next?