Navigation instructions

The Maps SDK for TypeScript offers comprehensive real-time navigation guidance, providing detailed information on the current and upcoming route, including road details, street names, speed limits, and turn directions. It delivers essential data such as remaining travel time, distance to destination, and upcoming turn or road information, ensuring users receive accurate, timely instructions. Designed for both navigation and simulation scenarios, this feature enhances the overall user experience by supporting smooth and efficient route planning and execution.

The main class responsible for turn-by-turn live navigation. guidance is the NavigationInstruction class.

note

It is important to distinguish between NavigationInstruction and RouteInstruction. NavigationInstruction offers real-time, turn-by-turn navigation based on the user's current position and is relevant only during navigation or simulation. In contrast, RouteInstruction provides an overview of the entire route available as soon as the route is calculated and the list of instructions do not change as the user navigates on the route.

Navigation instructions cannot be directly instantiated. Instead, they must be provided by the SDK while navigating. For detailed guidance on how to navigate on routes, refer to the Getting Started with Navigation Guide.

There are two main ways of getting a navigation instruction:

NavigationInstruction instances can be obtained via the callback provided as parameters to the startNavigation and startSimulation methods.
The NavigationService class provides a getNavigationInstruction method which returns the currently available navigation instruction. Make sure navigation/simulation is active before using the method provided above.

NavigationInstruction structure

Member	Type	Description
currentCountryCodeISO	string	Returns the ISO 3166-1 alpha-3 country code for the current navigation instruction. Empty string means no country.
currentStreetName	string	Returns the current street name.
currentStreetSpeedLimit	number	Returns the maximum speed limit on the current street in meters per second. Returns 0 if not available.
driveSide	DriveSide	Returns the drive side flag of the current traveled road.
hasNextNextTurnInfo	boolean	Returns true if next-next turn information is available.
hasNextTurnInfo	boolean	Returns true if next turn information is available.
instructionIndex	number	Returns the index of the current route instruction on the current route segment.
laneImg	LaneImg	Returns a customizable image representation of current lane configuration. The user is responsabile to verify if the image is valid.
navigationStatus	NavigationStatus	Returns the navigation/simulation status.
nextCountryCodeISO	string	Returns the ISO 3166-1 alpha-3 country code for the next navigation instruction.
nextNextStreetName	string	Returns the next-next street name.
nextNextTurnDetails	TurnDetails	Returns the full details for the next-next turn. Used for customizing turn display in UI.
nextNextTurnImg	Img	Returns a simplified schematic image of the next-next turn. The user is responsabile to verify if the image is valid.
nextNextTurnInstruction	string	Returns the textual description for the next-next turn.
getNextSpeedLimitVariation	NextSpeedLimit	Returns the next speed limit variation within specified check distance.
nextStreetName	string	Returns the next street name.
nextTurnDetails	TurnDetails	Returns the full details for the next turn. Used for customizing turn display in UI.
nextTurnImg	Img	Returns a simplified schematic image of the next turn. The user is responsabile to verify if the image is valid.
nextTurnInstruction	string	Returns the textual description for the next turn.
remainingTravelTimeDistance	TimeDistance	Returns the remaining travel time in seconds and distance in meters.
remainingTravelTimeDistanceToNextWaypoint	TimeDistance	Returns the remaining travel time in seconds and distance in meters to the next waypoint.
currentRoadInformation	RoadInfo[]	Returns the current road information list.
nextRoadInformation	RoadInfo[]	Returns the next road information list.
nextNextRoadInformation	RoadInfo[]	Returns the next-next road information list.
segmentIndex	number	Returns the index of the current route segment.
signpostDetails	SignpostDetails	Returns the extended signpost details.
signpostInstruction	string	Returns the textual description for the signpost information.
timeDistanceToNextNextTurn	TimeDistance	Returns the time (seconds) and distance (meters) to the next-next turn. Returns values for next turn if no next-next turn available.
timeDistanceToNextTurn	TimeDistance	Returns the time (seconds) and distance (meters) to the next turn.
traveledTimeDistance	TimeDistance	Returns the traveled time in seconds and distance in meters.

The field nextTurnInstruction provides a instruction in text format, suitable for displaying on UI. Please use the onTextToSpeechInstruction callback for getting a instruction suitable for text-to-speech.

Turn details

Next turn details

The following snippet shows how to extract detailed instructions for the next turn along the route. It's typically used in the navigation UI to show users the upcoming maneuver. You may also use this to provide turn-by-turn instructions with images or detailed text for navigation display:

import { NavigationInstruction, TurnDetails, TurnEvent } from '@magiclane/maps-sdk';

const navigationInstruction: NavigationInstruction = // ... obtained from navigation callback

// If hasNextTurnInfo is false some details are not available
const hasNextTurnInfo: boolean = navigationInstruction.hasNextTurnInfo;

if (hasNextTurnInfo) {
    // The next turn instruction
    const nextTurnInstruction: string = navigationInstruction.nextTurnInstruction;

    // The next turn details
    const turnDetails: TurnDetails = navigationInstruction.nextTurnDetails;

    // Turn event type (continue straight, turn right, turn left, etc.)
    const event: TurnEvent = turnDetails.event;

    // The image representation of the abstract geometry
    const abstractGeometryImage: Uint8Array | null = turnDetails.getAbstractGeometryImage({
        width: 300,
        height: 300
    });

    // The image representation of the next turn
    const turnImage: Uint8Array | null = navigationInstruction.getNextTurnImage({
        width: 300,
        height: 300
    });

    // Roundabout exit number (-1 if not a roundabout)
    const roundaboutExitNumber: number = turnDetails.roundaboutExitNumber;
}

See the TurnDetails guide for more details about the fields within the TurnDetails class.

Next next turn details

Details about the subsequent turn (i.e., the turn following the next one) can be crucial for certain use cases, such as providing a preview of upcoming maneuvers. These details can be accessed in a similar manner:

import { NavigationInstruction, TurnDetails } from '@magiclane/maps-sdk';

const navigationInstruction: NavigationInstruction = // ... obtained from navigation callback

// If hasNextNextTurnInfo is false some details are not available
const hasNextNextTurnInfo: boolean = navigationInstruction.hasNextNextTurnInfo;

if (hasNextNextTurnInfo) {
    const nextNextTurnInstruction: string = navigationInstruction.nextNextTurnInstruction;

    const nextNextTurnDetails: TurnDetails = navigationInstruction.nextNextTurnDetails;

    const nextNextTurnImage: Uint8Array | null = navigationInstruction.getNextNextTurnImage({
        width: 300,
        height: 300
    });
}

The hasNextNextTurnInfo might be false if the next instruction is the destination. The same operations discussed earlier for the next turn details can also be applied to the subsequent turn details.

Street information

Current street information

The following snippet shows how to get information about the current road:

import { NavigationInstruction, RoadInfo, DriveSide } from '@magiclane/maps-sdk';

const navigationInstruction: NavigationInstruction = // ... obtained from navigation callback

// Current street name
const currentStreetName: string = navigationInstruction.currentStreetName;

// Road info related to the current road
const currentRoadInfo: RoadInfo[] = navigationInstruction.currentRoadInformation;

// Country ISO code
const countryCode: string = navigationInstruction.currentCountryCodeISO;

// The drive direction (left or right)
const driveDirection: DriveSide = navigationInstruction.driveSide;

It is important to note that some streets may not have an assigned name. In such cases, currentStreetName will return an empty string. The RoadInfo class offers additional details, including the road name and shield type, which correspond to the official codes or names assigned to a road.

For example, the currentStreetName might return "Bloomsbury Street," while the roadname field in the associated RoadInfo instance could provide the official designation, such as "A400." This distinction ensures comprehensive road identification.

Next & next next street information

Information about the next street, as well as the street following it (next-next street), can also be retrieved. These details include the street name, type, and other associated metadata, enabling enhanced navigation and situational awareness:

import { NavigationInstruction, RoadInfo } from '@magiclane/maps-sdk';

const navigationInstruction: NavigationInstruction = // ... obtained from navigation callback

// Street name
const nextStreetName: string = navigationInstruction.nextStreetName;
const nextNextStreetName: string = navigationInstruction.nextNextStreetName;

// Road info
const nextRoadInformation: RoadInfo[] = navigationInstruction.nextRoadInformation;
const nextNextRoadInformation: RoadInfo[] = navigationInstruction.nextNextRoadInformation;

// Next country iso code
const nextCountryCodeISO: string = navigationInstruction.nextCountryCodeISO;

The fields associated with these streets retain the same meanings as discussed earlier about the current street.

warning

Ensure that hasNextTurnInfo and hasNextNextTurnInfo are true before attempting to access the respective fields. This verification prevents errors and ensures the availability of reliable data for the requested information.

Speed limit information

The NavigationInstruction class not only provides information about the current road's speed limit but also offers details about upcoming speed limits within a specified distance, assuming the user adheres to the recommended navigation route.

The following snippet demonstrates how to retrieve these details and handle various scenarios appropriately:

import { NavigationInstruction, NextSpeedLimit, Coordinates } from '@magiclane/maps-sdk';

const navigationInstruction: NavigationInstruction = // ... obtained from navigation callback

// The current street speed limit in m/s (0 if not available)
const currentStreetSpeedLimit: number = navigationInstruction.currentStreetSpeedLimit;

// Get next speed limit in 500 meters
const nextSpeedLimit: NextSpeedLimit = navigationInstruction.getNextSpeedLimitVariation(500);

// Coordinates where next speed limit changes
const coordinatesWhereSpeedLimitChanges: Coordinates = nextSpeedLimit.coords;

// Distance to where the next speed limit changes
const distanceToNextSpeedLimitChange: number = nextSpeedLimit.distance;

// Value of the next speed limit (m/s)
const nextSpeedLimitValue: number = nextSpeedLimit.speed;

if (distanceToNextSpeedLimitChange === 0 && nextSpeedLimitValue === 0) {
    console.log("The speed limit does not change within the specified interval");
} else if (nextSpeedLimitValue === 0) {
    console.log(
        "The speed limit changes in the specified interval but the value is not available");
} else {
    console.log(
        `The next speed limit changes to ${nextSpeedLimitValue} m/s in ${distanceToNextSpeedLimitChange} meters`);
}

Lane image

The lane image can be used to more effectively illustrate the correct lane for upcoming turns, providing clearer guidance:

import { NavigationInstruction, LaneImg, ImageFileFormat } from '@magiclane/maps-sdk';

const navigationInstruction: NavigationInstruction = // ... obtained from navigation callback

const laneImage: LaneImg = navigationInstruction.laneImage;
const laneImageData: Uint8Array | null = laneImage.getRenderableImageBytes({
    width: 500,
    height: 300,
    format: ImageFileFormat.png
});

Below is an example of a rendered lane image:

Lane image containing three lanes

Change the language of the instructions

The texts used in navigation instructions and related classes follow the language set in the SDK. See the internationalization guide for more details.

Instantiating navigation instructions​

NavigationInstruction structure​

Turn details​

Next turn details​

Next next turn details​

Street information​

Current street information​

Next & next next street information​

Speed limit information​

Lane image​

Change the language of the instructions​

Instantiating navigation instructions