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

• Directions API Documentation
• Navigation SDK for iOS
• Navigation SDK for Android
• Optimization API Documentation
• Map Matching API
• Navigation Products Overview

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