Roadblocks¶

A roadblock is a user-defined restriction applied to a specific road segment or geographic area, used to reflect traffic disruptions such as construction, closures, or areas to avoid.

It influences route planning by marking certain paths or zones as unavailable for navigation.

Roadblocks can be path-based (defined by a sequence of coordinates) or area-based (covering a geographic region), and may be either temporary or persistent, depending on their intended duration. Persistent roadblocks remain after a SDK uninitialization. Temporary roadblocks are short-lived.

The primary entity responsible for representing roadblocks is the UnlTrafficEvent class. Check the Traffic Events guide for more details. Roadblocks are mainly managed through the UnlTraffic class.

While some roadblocks are provided in real time by online data from UNL servers, users can also define their own user roadblocks to customize routing behavior.

If the applied style includes traffic data and traffic display is enabled (UnlMapViewPrefernces.setTrafficVisibility is set to true), a visual indication of the blocked portion will appear on the map, highlighted in red.

💡 TIP

Adding/removing user roadblocks affects only the current user and does not impact other users' routes. To create reports that are visible to all users, refer to the Social Reports guide.

Configure the traffic service¶

Traffic behavior can be customized through the UnlTrafficPreferences instance, accessible via the UnlTraffic class. The UnlTrafficPreferences class provides the useTraffic property, which defines how traffic data should be applied during routing and navigation.

The EUnlTrafficUsage enum offers the following configuration options:

Value	Description
`UseNone`	Disables all traffic data usage.
`UseOnline`	Uses both online and offline traffic data (default setting).
`UseOffline`	Uses only offline traffic data, including user-defined roadblocks.

For example, in order to set allow only offline usage the following line can be used:

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
traffic.preferences?.useTraffic = EUnlTrafficUsage.UseOffline

// Java
UnlTraffic traffic = new UnlTraffic();
UnlTrafficPreferences preferences = traffic.getPreferences();
if (preferences != null) {
    preferences.setUseTraffic(EUnlTrafficUsage.UseOffline);
}

A roadblock can be added to bypass a portion of the route for a specified distance. Once the roadblock is applied, the route will be recalculated, and the updated route will be returned via the onRouteUpdated callback provided to either the startNavigation or startSimulation method.

The snippet below will add a roadblock of 100 meters starting from the current position:

Kotlin
Java

// Kotlin
val navigationService = UnlNavigationService()
navigationService.setNavigationRoadBlock(100)

// Java
UnlNavigationService navigationService = new UnlNavigationService();
navigationService.setNavigationRoadBlock(100);

Roadblocks added through the setNavigationRoadBlock method provided by the UnlNavigationService only affect the ongoing navigation.

Check if a geographic position has traffic information¶

The getOnlineServiceRestrictions method can be used. It takes a UnlCoordinates object as argument and returns an integer containing flags from the ETrafficOnlineRestrictions enum.

For example, in order to check if traffic events are available for a certain geographic position:

Kotlin
Java

// Kotlin
val coords = UnlCoordinates(50.108, 8.783)
val traffic = UnlTraffic()
val restrictions = traffic.getOnlineServiceRestrictions(coords)

// Java
UnlCoordinates coords = new UnlCoordinates(50.108, 8.783);
UnlTraffic traffic = new UnlTraffic();
int restrictions = traffic.getOnlineServiceRestrictions(coords);

The ETrafficOnlineRestrictions enum provides the following values:

Settings: Online traffic is disabled in the UnlTrafficPreferences object.
Connection: No internet connection is available.
NetworkType: Not allowed on extra charged networks (e.g., roaming).
ProviderData: Required provider data is missing.
WorldMapVersion: The world map version is outdated and incompatible. Please update the road map.
DiskSpace: Insufficient disk space to download or store traffic data.

Add a user-defined persistent roadblock¶

To add a persistent user-defined roadblock, the user must provide the following:

startTime : the timestamp indicating when the roadblock becomes active.
expireTime : the timestamp indicating when the roadblock is no longer in effect.
transportMode : the specific mode of transport affected by the roadblock.
id : a unique string ID for the roadblock.
coords/area : either:

a list of coordinates (for path-based roadblocks), or
a geographic area (for area-based roadblocks).

When a user-defined roadblock is added, it will affect routing and navigation between the specified startTime and expireTime. Once the expireTime is reached, the roadblock is automatically removed without any user intervention.

🚨 DANGER

The following conditions apply when adding a roadblock:

If roadblocks are disabled in the UnlTrafficPreferences object, the addition will fail and return null.

If a roadblock already exists at the same location where the user attempts to add a new one, the operation will fail and return null.

If the input parameters are invalid (e.g., expireTime is later than startTime, missing id, or invalid coordinates/area object), the addition will fail and return null.

If a roadblock with the same id already exists, the addition will fail and return null.

Add a area-based persistent roadblock¶

The addPersistentRoadblock method with a UnlGeographicArea parameter is used to add area-based user roadblocks. It accepts a UnlGeographicArea object which represents the area to be avoided.

The method returns:

If the addition is successful, the method returns the newly created UnlTrafficEvent instance.
If the addition fails, the method returns null.

For example, adding a area-based user-defined persistent roadblock on a given area, starting from now and available for 1 hour which affects cars can be done in the following way:

Kotlin
Java

// Kotlin
val topLeft = UnlCoordinates(46.764942, 7.122563)
val bottomRight = UnlCoordinates(46.762031, 7.127992)
val area = RectangleGeographicArea(topLeft, bottomRight)

val startTime = UnlTime.getUniversalTime()
val endTime = UnlTime.getUniversalTime()?.apply { minute += 60 }

val traffic = UnlTraffic()
val trafficEvent = if (startTime != null && endTime != null) {
    traffic.addPersistentRoadblock(
        area = area,
        startUTC = startTime,
        expireUTC = endTime,
        transportMode = EUnlRouteTransportMode.Car.value,
        id = "test_id"
    )
} else null

if (trafficEvent != null) {
    println("The addition was successful")
} else {
    println("The addition failed")
}

// Java
UnlCoordinates topLeft = new UnlCoordinates(46.764942, 7.122563);
UnlCoordinates bottomRight = new UnlCoordinates(46.762031, 7.127992);
RectangleGeographicArea area = new RectangleGeographicArea(topLeft, bottomRight);

UnlTime startTime = UnlTime.getUniversalTime();
UnlTime endTime = UnlTime.getUniversalTime();

UnlTraffic traffic = new UnlTraffic();
UnlTrafficEvent trafficEvent = null;
if (startTime != null && endTime != null) {
    endTime.setMinute(endTime.getMinute() + 60);
    trafficEvent = traffic.addPersistentRoadblock(
        area,
        startTime,
        endTime,
        EUnlRouteTransportMode.Car.getValue(),
        "test_id"
    );
}

if (trafficEvent != null) {
    System.out.println("The addition was successful");
} else {
    System.out.println("The addition failed");
}

Add a path-based persistent roadblock¶

The addPersistentRoadblock method with a UnlCoordinatesList parameter is used to add path-based user roadblocks. It accepts a list of UnlCoordinates objects and supports two modes of operation:

Single Coordinate: Defines a point-based roadblock. This may result in two roadblocks being created - one for each travel direction.
Multiple UnlCoordinates: Defines a path-based roadblock, starting at the first coordinate and ending at the last. This is used to restrict access along a specific road segment.

For example, adding a path-based user-defined persistent roadblock on both sides of the matching road, starting from now and available for 1 hour which affects cars can be done in the following way:

Kotlin
Java

// Kotlin
val coords = arrayListOf(UnlCoordinates(405.847994, 24.956233))

val startTime = UnlTime.getUniversalTime()
val endTime = UnlTime.getUniversalTime()?.apply { minute += 60 }

val traffic = UnlTraffic()
val trafficEvent = if (startTime != null && endTime != null) {
    traffic.addPersistentRoadblock(
        coords = coords,
        startUTC = startTime,
        expireUTC = endTime,
        transportMode = EUnlRouteTransportMode.Car.value,
        id = "test_id"
    )
} else null

if (trafficEvent != null) {
    println("The addition was successful")
} else {
    println("The addition failed")
}

// Java
ArrayList<UnlCoordinates> coords = new ArrayList<>();
coords.add(new UnlCoordinates(405.847994, 24.956233));

UnlTime startTime = UnlTime.getUniversalTime();
UnlTime endTime = UnlTime.getUniversalTime();

UnlTraffic traffic = new UnlTraffic();
UnlTrafficEvent trafficEvent = null;
if (startTime != null && endTime != null) {
    endTime.setMinute(endTime.getMinute() + 60);
    trafficEvent = traffic.addPersistentRoadblock(
        coords,
        startTime,
        endTime,
        EUnlRouteTransportMode.Car.getValue(),
        "test_id"
    );
}

if (trafficEvent != null) {
    System.out.println("The addition was successful");
} else {
    System.out.println("The addition failed");
}

The method returns the result in a similar way to the area-based method.

🚨 DANGER

In addition to the scenarios described above, the path-based addPersistentRoadblock method may also fail in the following cases:

No Suitable Road Found: If a valid road cannot be identified at the specified coordinates, or if no road data (online or offline) is available for the given location, the method will return null.

Route Computation Failed: If multiple coordinates are provided but a valid route cannot be computed between them, the method will return null.

Add an anti-area persistent roadblock¶

📝 INFO

The Android SDK does not currently provide a specific method for creating anti-area roadblocks. This functionality may be available in future versions of the SDK.

Get all user-defined persistent roadblocks¶

The persistentRoadblocks property provided by the UnlTraffic class provides the list of persistent roadblocks.

The following snippet iterates through all persistent roadblocks - both path-based and area-based - and prints their descriptions.

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
val roadblocks = traffic.persistentRoadblocks

roadblocks?.forEach { roadblock ->
    if (roadblock.isUserRoadblock())
        println(roadblock.description)
}

// Java
UnlTraffic traffic = new UnlTraffic();
List<UnlTrafficEvent> roadblocks = traffic.getPersistentRoadblocks();

if (roadblocks != null) {
    for (UnlTrafficEvent roadblock : roadblocks) {
        if (roadblock.isUserRoadblock()) {
            System.out.println(roadblock.getDescription());
        }
    }
}

All user-defined roadblocks that are currently active or scheduled to become active are returned. Expired roadblocks are automatically removed.

Get user-defined persistent roadblocks¶

📝 INFO

The Android SDK does not currently provide a specific method to get a roadblock by ID. You can iterate through the persistentRoadblocks list to find a specific roadblock by comparing IDs or other properties.

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
val roadblocks = traffic.persistentRoadblocks
val targetId = "unique_id"

val event = roadblocks?.find { it.description == targetId }

if (event != null) {
    println("Event was found")
} else {
    println("Event does not exist")
}

// Java
UnlTraffic traffic = new UnlTraffic();
List<UnlTrafficEvent> roadblocks = traffic.getPersistentRoadblocks();
String targetId = "unique_id";

UnlTrafficEvent event = null;
if (roadblocks != null) {
    for (UnlTrafficEvent rb : roadblocks) {
        if (targetId.equals(rb.getDescription())) {
            event = rb;
            break;
        }
    }
}

if (event != null) {
    System.out.println("Event was found");
} else {
    System.out.println("Event does not exist");
}

Remove user-defined roadblocks¶

Remove persistent user-defined roadblock by id¶

Use the removePersistentRoadblock method with a string ID to remove a roadblock if the identifier is known.

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
val errorCode = traffic.removePersistentRoadblock("identifier")
if (errorCode == UnlError.Success) {
    println("Removal succeeded")
} else {
    println("Removal failed with error code $errorCode")
}

// Java
UnlTraffic traffic = new UnlTraffic();
int errorCode = traffic.removePersistentRoadblock("identifier");
if (errorCode == UnlError.Success) {
    System.out.println("Removal succeeded");
} else {
    System.out.println("Removal failed with error code " + errorCode);
}

The method returns UnlError.Success if the roadblock was removed and UnlError.NotFound if no roadblock was found with the given id. This method works both for path-based and area-based roadblocks.

Remove persistent user-defined roadblock by coordinates¶

Use the removePersistentRoadblock method with a UnlCoordinates parameter to remove path-based roadblocks by providing the method with the first coordinate of the roadblock to be removed.

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
val errorCode = traffic.removePersistentRoadblock(coords)
if (errorCode == UnlError.Success) {
    println("Removal succeeded")
} else {
    println("Removal failed with error code $errorCode")
}

// Java
UnlTraffic traffic = new UnlTraffic();
int errorCode = traffic.removePersistentRoadblock(coords);
if (errorCode == UnlError.Success) {
    System.out.println("Removal succeeded");
} else {
    System.out.println("Removal failed with error code " + errorCode);
}

The method returns UnlError.Success if the roadblock was removed and UnlError.NotFound if no roadblock was found starting with the given coordinate.

Remove user-defined roadblock given the UnlTrafficEvent¶

If the UnlTrafficEvent instance is available, it can be removed using the removeUserRoadblock method:

Kotlin
Java

// Kotlin
val event: UnlTrafficEvent = // ... obtained from somewhere
val traffic = UnlTraffic()
traffic.removeUserRoadblock(event)

// Java
UnlTrafficEvent event = // ... obtained from somewhere
UnlTraffic traffic = new UnlTraffic();
traffic.removeUserRoadblock(event);

💡 TIP

This method can be used for both persistent and non-persistent roadblocks.

Remove all user-defined persistent roadblocks¶

Use the removeAllPersistentRoadblocks method to delete all existing user-defined roadblocks.

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
traffic.removeAllPersistentRoadblocks()

// Java
UnlTraffic traffic = new UnlTraffic();
traffic.removeAllPersistentRoadblocks();

Get preview of a path-based user-defined roadblock¶

📝 INFO

The Android SDK does not currently provide a specific method for generating roadblock path previews. This functionality may be available in future versions of the SDK, or you can implement path preview by using the routing services to calculate routes between coordinates.

Persistent roadblock listener¶

The Navigation SDK for Android also allows users to register for notifications related to persistent roadblocks. These notifications are triggered in the following cases:

When a roadblock's startTime becomes greater than the current time - via the onRoadblocksActivated callback
When a roadblock's endTime becomes less than the current time - via the onRoadblocksExpired callback

These callbacks provide the activated/expired TrafficEventList.

Create a PersistentRoadblockListener instance:

Kotlin
Java

// Kotlin
val listener = object : PersistentRoadblockListener() {
    override fun onRoadblocksActivated(list: TrafficEventList) {
        // Do something with the activated events
        list.forEach { event ->
            println("Roadblock activated: ${event.description}")
        }
    }

    override fun onRoadblocksExpired(list: TrafficEventList) {
        // Do something with the expired events
        list.forEach { event ->
            println("Roadblock expired: ${event.description}")
        }
    }
}

// Java
PersistentRoadblockListener listener = new PersistentRoadblockListener() {
    @Override
    public void onRoadblocksActivated(TrafficEventList list) {
        // Do something with the activated events
        for (UnlTrafficEvent event : list) {
            System.out.println("Roadblock activated: " + event.getDescription());
        }
    }

    @Override
    public void onRoadblocksExpired(TrafficEventList list) {
        // Do something with the expired events
        for (UnlTrafficEvent event : list) {
            System.out.println("Roadblock expired: " + event.getDescription());
        }
    }
};

Register the listener using the setPersistentRoadblockListener method of the UnlTraffic class:

Kotlin
Java

// Kotlin
val traffic = UnlTraffic()
traffic.setPersistentRoadblockListener(listener)

// Java
UnlTraffic traffic = new UnlTraffic();
traffic.setPersistentRoadblockListener(listener);

Roadblocks¶

Configure the traffic service​¶

Add a temporary user roadblock while in navigation​¶

Check if a geographic position has traffic information​¶

Add a user-defined persistent roadblock​¶

Add a area-based persistent roadblock​¶

Add a path-based persistent roadblock​¶

Add an anti-area persistent roadblock​¶

Get all user-defined persistent roadblocks​¶

Get user-defined persistent roadblocks​¶

Remove user-defined roadblocks​¶

Remove persistent user-defined roadblock by id​¶

Remove persistent user-defined roadblock by coordinates​¶

Remove user-defined roadblock given the UnlTrafficEvent​¶

Remove all user-defined persistent roadblocks​¶

Get preview of a path-based user-defined roadblock​¶

Persistent roadblock listener​¶