Mapbox Navigation Patterns
Expert guidance for implementing navigation and routing features using Mapbox Directions API and Navigation SDKs. Covers turn-by-turn navigation, route optimization, real-time traffic integration, multi-stop routing, and navigation UI components.
Use This Skill When
User says things like:
- "I need turn-by-turn navigation in my app"
- "How do I add driving directions?"
- "I want to show a route on the map"
- "I need multi-stop routing"
- "How do I add voice guidance?"
- "I want real-time traffic updates"
- "I need to optimize delivery routes"
Product Overview
Directions API (REST)
Best for: Web applications, simple routing, backend route calculation
Features:
- Route calculation (driving, walking, cycling, traffic)
- Alternative routes
- Turn-by-turn instructions
- Multi-stop routing (up to 25 waypoints)
- Route optimization
- Real-time traffic data
- Avoid specific roads/areas
Pricing: Pay per request
Navigation SDK for iOS
Best for: Native iOS apps with turn-by-turn navigation
Defaults: SwiftUI app shell + wrap drop-in NavigationViewController via UIViewControllerRepresentable (official getting-started path). Use a fully custom Core UI (CoreSDKExample) only when the user explicitly wants to build their own nav chrome.
Before coding: SPM (MapboxNavigationCore + MapboxNavigationUIKit), .netrc download token, MBXAccessToken, location permissions, background audio/location — see install guide and the iOS reference checklist.
Features:
- Drop-in turn-by-turn UI (
NavigationViewController) — default
- Optional fully custom Core UI (route progress / banner publishers)
- Voice guidance (30+ languages)
- Real-time rerouting
- Traffic-aware routing
- Offline maps and routing
- Route progress tracking
- Speed limit display
Pricing: Monthly Active Users (MAU) based
Navigation SDK for Android
Best for: Native Android apps with turn-by-turn navigation
Features:
- Complete turn-by-turn navigation UI
- Voice guidance (30+ languages)
- Real-time rerouting
- Traffic-aware routing
- Offline maps and routing
- Custom UI components
- Route progress tracking
- Speed limit display
Pricing: Monthly Active Users (MAU) based
Decision Guide
Choose Directions API when:
- ✅ Web application
- ✅ Simple route display (no turn-by-turn)
- ✅ Backend route calculation
- ✅ Route planning and optimization
- ✅ Multi-stop routing
- ✅ Don't need voice guidance
Choose Navigation SDK when:
- ✅ Native mobile app (iOS/Android)
- ✅ Need turn-by-turn navigation
- ✅ Need voice guidance
- ✅ Need navigation UI components
- ✅ Need offline navigation
- ✅ Need real-time rerouting
- ✅ Building a navigation/delivery app
Implementation Patterns
- references/web-directions-api.md - Directions API patterns for the web: basic route display, turn-by-turn instructions, alternative routes, multi-stop routing, route optimization, and congestion-based route coloring
- references/ios-navigation-sdk.md - When: iOS turn-by-turn, setup, default SwiftUI + wrapped
NavigationViewController, Core opt-in, example catalog
- references/ios-navigation-specialized.md - When: multi-stop, route line, camera, road cameras, route alerts, or
NavigationMapView customization
- references/android-navigation-sdk.md - Navigation SDK for Android: basic turn-by-turn navigation, custom navigation UI, route line rendering, maneuver arrows, navigation camera, voice guidance
- references/android-performance-antipatterns.md - Android Navigation SDK performance and correctness antipatterns: Native Route Object traversal costs, threading, memory/lifecycle leaks, route management correctness, frequent-callback rendering efficiency, and Coordination API lifecycle
- references/best-practices.md - Route caching, error handling, performance optimization, user experience, and common use cases (delivery routing, ride-sharing ETAs, walking/cycling directions)
Related Skills
- mapbox-search-integration: Address search and geocoding
- mapbox-web-performance-patterns: Optimizing navigation performance
- mapbox-ios-patterns: iOS-specific integration patterns
- mapbox-android-patterns: Android-specific integration patterns
- mapbox-token-security: Securing your access tokens
Resources
Quick Decision Guide
User says: "I need directions"
- Web app → Use Directions API
- Mobile app → Use Navigation SDK
User says: "I need turn-by-turn navigation"
- iOS → Navigation SDK for iOS (SwiftUI + wrapped
NavigationViewController by default; Core custom UI only if requested)
- Android → Navigation SDK for Android
- Web → Use Directions API + custom UI (no voice guidance)
User says: "I need to optimize delivery routes"
→ Use Optimization API (multi-stop route optimization)
User says: "I need real-time traffic"
→ Use driving-traffic profile with Directions API or Navigation SDK
User says: "I need voice guidance"
→ Must use Navigation SDK (iOS/Android only)
User says: "Directions API or Navigation SDK?"
→ Native turn-by-turn / voice → Navigation SDK (MAU pricing). Web / route display only → Directions API (pay-per-request).
1---
2name: mapbox-navigation-patterns
3description: Navigation implementation patterns for turn-by-turn directions, route optimization, real-time traffic, multi-stop routing, and voice guidance across web, iOS, and Android platforms
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/mapbox-navigation-patterns
6---
7
8# Mapbox Navigation Patterns
9
10Expert guidance for implementing navigation and routing features using Mapbox Directions API and Navigation SDKs. Covers turn-by-turn navigation, route optimization, real-time traffic integration, multi-stop routing, and navigation UI components.
11
12## Use This Skill When
13
14User says things like:
15
16- "I need turn-by-turn navigation in my app"
17- "How do I add driving directions?"
18- "I want to show a route on the map"
19- "I need multi-stop routing"
20- "How do I add voice guidance?"
21- "I want real-time traffic updates"
22- "I need to optimize delivery routes"
23
24## Product Overview
25
26### Directions API (REST)
27
28**Best for:** Web applications, simple routing, backend route calculation
29
30**Features:**
31
32- Route calculation (driving, walking, cycling, traffic)
33- Alternative routes
34- Turn-by-turn instructions
35- Multi-stop routing (up to 25 waypoints)
36- Route optimization
37- Real-time traffic data
38- Avoid specific roads/areas
39
40**Pricing:** Pay per request
41
42### Navigation SDK for iOS
43
44**Best for:** Native iOS apps with turn-by-turn navigation
45
46**Defaults:** SwiftUI app shell + wrap drop-in `NavigationViewController` via `UIViewControllerRepresentable` (official getting-started path). Use a fully custom Core UI ([CoreSDKExample](https://github.com/mapbox/mapbox-navigation-ios/tree/main/Examples/CoreSDKExample)) only when the user explicitly wants to build their own nav chrome.
47
48**Before coding:** SPM (`MapboxNavigationCore` + `MapboxNavigationUIKit`), `.netrc` download token, `MBXAccessToken`, location permissions, background `audio`/`location` — see [install guide](https://docs.mapbox.com/ios/navigation/guides/install/) and the iOS reference checklist.
49
50**Features:**
51
52- Drop-in turn-by-turn UI (`NavigationViewController`) — default
53- Optional fully custom Core UI (route progress / banner publishers)
54- Voice guidance (30+ languages)
55- Real-time rerouting
56- Traffic-aware routing
57- Offline maps and routing
58- Route progress tracking
59- Speed limit display
60
61**Pricing:** Monthly Active Users (MAU) based
62
63### Navigation SDK for Android
64
65**Best for:** Native Android apps with turn-by-turn navigation
66
67**Features:**
68
69- Complete turn-by-turn navigation UI
70- Voice guidance (30+ languages)
71- Real-time rerouting
72- Traffic-aware routing
73- Offline maps and routing
74- Custom UI components
75- Route progress tracking
76- Speed limit display
77
78**Pricing:** Monthly Active Users (MAU) based
79
80## Decision Guide
81
82### Choose Directions API when:
83
84- ✅ Web application
85- ✅ Simple route display (no turn-by-turn)
86- ✅ Backend route calculation
87- ✅ Route planning and optimization
88- ✅ Multi-stop routing
89- ✅ Don't need voice guidance
90
91### Choose Navigation SDK when:
92
93- ✅ Native mobile app (iOS/Android)
94- ✅ Need turn-by-turn navigation
95- ✅ Need voice guidance
96- ✅ Need navigation UI components
97- ✅ Need offline navigation
98- ✅ Need real-time rerouting
99- ✅ Building a navigation/delivery app
100
101## Implementation Patterns
102
103- **[references/web-directions-api.md](references/web-directions-api.md)** - Directions API patterns for the web: basic route display, turn-by-turn instructions, alternative routes, multi-stop routing, route optimization, and congestion-based route coloring
104- **[references/ios-navigation-sdk.md](references/ios-navigation-sdk.md)** - When: iOS turn-by-turn, setup, default SwiftUI + wrapped `NavigationViewController`, Core opt-in, example catalog
105- **[references/ios-navigation-specialized.md](references/ios-navigation-specialized.md)** - When: multi-stop, route line, camera, road cameras, route alerts, or `NavigationMapView` customization
106- **[references/android-navigation-sdk.md](references/android-navigation-sdk.md)** - Navigation SDK for Android: basic turn-by-turn navigation, custom navigation UI, route line rendering, maneuver arrows, navigation camera, voice guidance
107- **[references/android-performance-antipatterns.md](references/android-performance-antipatterns.md)** - Android Navigation SDK performance and correctness antipatterns: Native Route Object traversal costs, threading, memory/lifecycle leaks, route management correctness, frequent-callback rendering efficiency, and Coordination API lifecycle
108- **[references/best-practices.md](references/best-practices.md)** - Route caching, error handling, performance optimization, user experience, and common use cases (delivery routing, ride-sharing ETAs, walking/cycling directions)
109
110## Related Skills
111
112- **mapbox-search-integration**: Address search and geocoding
113- **mapbox-web-performance-patterns**: Optimizing navigation performance
114- **mapbox-ios-patterns**: iOS-specific integration patterns
115- **mapbox-android-patterns**: Android-specific integration patterns
116- **mapbox-token-security**: Securing your access tokens
117
118## Resources
119
120- [Directions API Documentation](https://docs.mapbox.com/api/navigation/directions/)
121- [Navigation SDK for iOS](https://docs.mapbox.com/ios/navigation/)
122- [Navigation SDK for Android](https://docs.mapbox.com/android/navigation/)
123- [Optimization API Documentation](https://docs.mapbox.com/api/navigation/optimization/)
124- [Map Matching API](https://docs.mapbox.com/api/navigation/map-matching/)
125- [Navigation Products Overview](https://docs.mapbox.com/help/getting-started/navigation/)
126
127## Quick Decision Guide
128
129**User says: "I need directions"**
130
131- Web app → Use Directions API
132- Mobile app → Use Navigation SDK
133
134**User says: "I need turn-by-turn navigation"**
135
136- iOS → Navigation SDK for iOS (SwiftUI + wrapped `NavigationViewController` by default; Core custom UI only if requested)
137- Android → Navigation SDK for Android
138- Web → Use Directions API + custom UI (no voice guidance)
139
140**User says: "I need to optimize delivery routes"**
141→ Use Optimization API (multi-stop route optimization)
142
143**User says: "I need real-time traffic"**
144→ Use `driving-traffic` profile with Directions API or Navigation SDK
145
146**User says: "I need voice guidance"**
147→ Must use Navigation SDK (iOS/Android only)
148
149**User says: "Directions API or Navigation SDK?"**
150→ Native turn-by-turn / voice → Navigation SDK (**MAU** pricing). Web / route display only → Directions API (**pay-per-request**).