Turn-by-turn instructions

VERSION 0.34.2

The Navigation SDK for iOS is only available upon request. Contact us to get started.

Planning a route for turn-by-turn navigation requires that specific parameters be included in the request. An example of routing options that can be used for this purpose is as follows:

1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)
2let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)
3
4let itinerary = Itinerary(
5    origin: ItineraryPoint(coordinate: amsterdamCoordinate),
6    destination: ItineraryPoint(coordinate: berlinCoordinate)
7)
8
9let options: RoutePlanningOptions
10do {
11    options = try RoutePlanningOptions(
12        itinerary: itinerary,
13        guidanceOptions: GuidanceOptions(
14            instructionType: .tagged,
15            language: Locale(identifier: "en-GB"),
16            announcementPoints: .all,
17            phoneticsType: .IPA
18        )
19    )
20} catch {
21    print("Invalid planning options: \(error.localizedDescription)")
22}

The most important parameters are summarized below.

Instructions

To obtain guidance instructions, GuidanceOptions.instructionType needs to be set. Possible values are:

InstructionType.coded: returns raw instruction data without human-readable messages.
InstructionType.text: returns raw instructions data with human-readable messages in plain text.
InstructionType.tagged: returns raw instruction data with tagged human-readable messages to permit formatting.

If alternative routes are requested, instructions will be generated for each route returned.

Announcement points

RoutePlanningOptions.init()

The GuidanceOptions.announcementPoints parameter specifies whether to include announcement points in instructions. If specified, the instruction will include up to three additional fine-grained announcement points, each with its location, maneuver type, and distance to the instruction point. Based on that, the navigation system can decide at which point of time the audio messages should be played. Possible values are:

AnnouncementPoints.none: Do not include instruction announcement points.
AnnouncementPoints.all: Include instruction announcement points. If the method is called with value AnnouncementPoints.all, the instruction will include up to three additional fine-grained announcement points, each with its own location, maneuver type, and distance to the instruction point.

If the GuidanceOptions.announcementPoints parameter is not set, instructions will not include any announcements.

Road shield references

The GuidanceOptions.roadShieldReferences parameter specifies whether to include road shield references into the external road shields atlas. Possible values are:

RoadShieldReferences.none: Do not include instruction road shield references.
RoadShieldReferences.all: Include instructions for road shield references.

If the GuidanceOptions.roadShieldReferences parameter is not set, instructions will not include any road shield references.

Phonetics

The GuidanceOptions.phoneticsType parameter specifies whether to include phonetic transcriptions of street names, signpost texts, and road numbers in the instructions. In areas where phonetic information is not available, the result will not be returned. Possible values are:

InstructionPhoneticsType.none: Do not include phonetic transcriptions in the response.
InstructionPhoneticsType.LHP: Return phonetic transcriptions in the L&H+ format from Cerence Inc.
InstructionPhoneticsType.IPA: Return phonetic transcriptions in the IPA (International Phonetic Alphabet).

If the GuidanceOptions.phoneticsType parameter is not set, instructions will not include any phonetic transcriptions.

Vehicle heading

When driving, it’s important to request a route in a specific direction. For that purpose, the ItineraryPoint.heading parameter should be used. It describes the directional heading of the vehicle, in degrees starting at true North and continuing in a clockwise direction:

North is 0 degrees.
East is 90 degrees.
South is 180 degrees.
West is 270 degrees.

Route sections

Per default, all sections except for lanes, speed limits, and roadshields are included in the response. If you want to include these three as well, specify ExtendedSections.all with GuidanceOptions.extendedSections.

More details about available route sections can be found in the Sections document.

To get the best turn-by-turn experience, it’s required to include the extended sections as well.

Progress points

The GuidanceOptions.progressPoints parameter specifies whether the response should include progress points. Progress points consist of a list of references to polyline points, annotated with a value indicating travelTime or distance up to that point. Possible values are:

ProgressPoints.none - Do not include progress points in the response.
ProgressPoints.all - Include both progress point types in the response.

Next steps

Since you have learned how to work with turn-by-turn instructions, here are recommendations for the next steps: