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

Navigation services comprise the following services:

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.
Distance Matrix Async API - receives requests for the asynchronous part of the Distance Matrix API and passes them to Navi-Back. The interaction between Distance Matrix Async API and Navi-Back is described in the Processing asynchronous requests to Distance Matrix API section
Restrictions API — provides information about road closures. See the Restrictions API section.

A Traffic Proxy service is used to get real-time traffic data from Traffic Servers. Navi-Back service uses this data to build routes that consider traffic conditions.

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

Processing asynchronous requests to Distance Matrix API

To implement support for the asynchronous part of the Distance Matrix API, which is necessary for processing large numbers of points, you need to install the Distance Matrix Async API service. 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.

Distance Matrix API (On-Premise) service architecture

Requests are processed as follows:

The user sends a request to Distance Matrix Async API.
Distance Matrix Async API saves the request data into the S3 storage.
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.
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.
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.

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?

Find out how to install or update the services:
- Installing navigation API
- Updating navigation API
Read more about On-Premise:
- Solution architecture
- System requirements