# Magic Lane - Maps SDK for iOS documentation


## Docs

- [Get Started With Sample Apps](/docs/ios/examples/get-started-with-sample-apps.md): Prerequisites
- [Maps & 3D Scene](/docs/ios/examples/maps-3dscene.md): These articles provide extensive coverage of the map related functionalities and techniques for both UIKit and SwiftUI implementations.
- [Center Map](/docs/ios/examples/maps-3dscene/center-map.md): This example demonstrates how to use GEMKit in a UIKit application to programmatically center the map on a specific coordinate.
- [Following Position](/docs/ios/examples/maps-3dscene/following-position.md): This example demonstrates how to use GEMKit in a UIKit application to follow the position on the map after requesting location permission.
- [Hello Map](/docs/ios/examples/maps-3dscene/hello-map.md): This example demonstrates how to use GEMKit in a UIKit application to display a fully interactive map view.
- [Map Update](/docs/ios/examples/maps-3dscene/map_update.md): This example demonstrates how to use GEMKit in a UIKit application to update the maps. There are two scenarios explained here, the manual update that is mandatory when having offline maps downloaded, and the default automatic update when no offline maps are used.
- [Map Compass](/docs/ios/examples/maps-3dscene/map-compass.md): This example demonstrates how to use GEMKit in a UIKit application to customize the compass.
- [Map Download](/docs/ios/examples/maps-3dscene/map-download.md): This example demonstrates how to use GEMKit in a UIKit application to display multiple maps simultaneously.
- [Map Perspective](/docs/ios/examples/maps-3dscene/map-perspective.md): This example demonstrates how to use GEMKit in a UIKit application to follow the position on the map after requesting location permission.
- [Map Render](/docs/ios/examples/maps-3dscene/map-render.md): This example demonstrates how to use GEMKit in a UIKit application to handle the map rendering based on the view controller's lifecycle.
- [Map Selection](/docs/ios/examples/maps-3dscene/map-selection.md): This example demonstrates how to handle user interactions with map elements (e.g. streets, landmarks, overlays, and traffic events) and apply custom highlight styles using HighlightRenderSettings in a UIKit application.
- [Map Custom Style](/docs/ios/examples/maps-3dscene/map-style.md): This example demonstrates how to apply a custom map style in a UIKit application. A custom map style can be created in our Map Studio.
- [Map Style Following Theme](/docs/ios/examples/maps-3dscene/map-style-following-theme.md): This example demonstrates how to use GEMKit in a UIKit application to apply a map style that follows the device theme (light/dark mode).
- [Multi-Map](/docs/ios/examples/maps-3dscene/multi-map.md): This example demonstrates how to use GEMKit in a UIKit application to display multiple maps simultaneously.
- [Position Tracker](/docs/ios/examples/maps-3dscene/position-tracker.md): This example demonstrates how to change the map's Position Tracker in a UIKit application.
- [Projections](/docs/ios/examples/maps-3dscene/projections.md): This example demonstrates how to use GEMKit in a UIKit application to convert the coordinates of a selected landmark to different projections and display the results in a table view.
- [Range](/docs/ios/examples/maps-3dscene/range.md): This example demonstrates how to use GEMKit in a UIKit application to display multiple maps simultaneously.
- [Shapes](/docs/ios/examples/maps-3dscene/shapes.md): This example demonstrates how to use GEMKit in a UIKit application to draw Shapes on the map using Markers.
- [Places & Search](/docs/ios/examples/places-search.md): These articles cover places and search functionality for both UIKit and SwiftUI implementations.
- [Address Search](/docs/ios/examples/places-search/address-search.md): This example demonstrates how to use GEMKit in a UIKit application to resolve a full street address step-by-step, from country detection through state, city, street, and house number, using the hierarchical addressSearch API of SearchContext.
- [Group Search Results](/docs/ios/examples/places-search/group-search-results.md): This example demonstrates how to use GEMKit in a UIKit application to display and center the results of a text search on the map as Highlights, with grouping enabled and a custom pin image.
- [Search Category](/docs/ios/examples/places-search/search_category.md): This example demonstrates how to use GEMKit in a UIKit application to search for Landmarks in a specific category.
- [Search Along Route](/docs/ios/examples/places-search/search-along-route.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a car route, search for landmarks along it using SearchContext, and display the results as grouped Highlights on the map.
- [Search on Map](/docs/ios/examples/places-search/search-on-map.md): This example demonstrates how to use GEMKit in a UIKit application to perform searches on the map, including searching for nearby landmarks and landmarks matching a specific query. Searching on the map chooses the center point as the location reference.
- [Search Text](/docs/ios/examples/places-search/search-text.md): This example demonstrates how to use GEMKit in a UIKit application to search for Landmarks using a text query.
- [What's Nearby](/docs/ios/examples/places-search/whats-nearby.md): This example demonstrates how to use GEMKit in a UIKit application to perform searches for nearby landmarks around a specific location.
- [Routing & Navigation](/docs/ios/examples/routing-navigation.md)
- [Better Route Notification](/docs/ios/examples/routing-navigation/better-route-notification.md): This example demonstrates how to use GEMKit in a UIKit application to detect when a faster alternate route becomes available during navigation and then offer it to the user.
- [Calculate Route](/docs/ios/examples/routing-navigation/calculate-route.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a car route between two coordinates and display it on the map with a summary panel.
- [Calculate Route Multi Map](/docs/ios/examples/routing-navigation/calculate-route-multi-map.md): This example demonstrates how to use GEMKit in a UIKit application to display two independent MapViewController instances side-by-side, each calculating and presenting its own route with a separate NavigationContext.
- [Custom Turns ID](/docs/ios/examples/routing-navigation/custom-turns-id.md): This example demonstrates how to use GEMKit in a UIKit application to replace the default SDK turn icons with custom images keyed by the numeric TurnId64 value of each upcoming manoeuvre.
- [Finger Draw Route](/docs/ios/examples/routing-navigation/finger-drawn-route-navigation.md): This example demonstrates how to use GEMKit in a UIKit application to draw a path on the map and calculate a route from that path, with the option to share it as a .gpx file.
- [Follow Position Preferences](/docs/ios/examples/routing-navigation/follow-position-preferences.md): This example demonstrates how to use GEMKit in a UIKit application to customise the follow-position camera behaviour so the user's pinch and drag adjustments to zoom level and tilt angle are persisted across the session, and can be reset to defaults on demand.
- [GPX Route](/docs/ios/examples/routing-navigation/gpx-route.md): This example demonstrates how to use GEMKit in a UIKit application to load a .gpx file bundled with the app, calculate a route that follows the track, display it on the map, and simulate riding it.
- [GPX Thumbnail Image](/docs/ios/examples/routing-navigation/gpx-thumbnail-image.md): This example demonstrates how to use GEMKit in a UIKit application to generate a static map thumbnail image from a .gpx track without displaying a full interactive map to the user.
- [Human Voices](/docs/ios/examples/routing-navigation/human-voices.md): This example demonstrates how to use GEMKit in a UIKit application to download and use human-recorded voice packages for turn-by-turn navigation guidance via HumanVoiceContext.
- [Navigate Route](/docs/ios/examples/routing-navigation/navigate-route.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a route using the device's real GPS position as the departure point and navigate it turn-by-turn with voice guidance.
- [No Map Just Routing](/docs/ios/examples/routing-navigation/no-map-just-routing.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a route and run turn-by-turn guidance entirely without a map view, using only labels and a navigation panel overlay.
- [Public Transit Calculate Route](/docs/ios/examples/routing-navigation/public-transit-calculate-route.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a public transit route between two locations and render it on the map with a route summary.
- [Public Transit Route Instructions](/docs/ios/examples/routing-navigation/public-transit-route-instructions.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a public transit route and display a detailed step-by-step breakdown of each transit segment, including departure times, line colours, and walking legs.
- [Road Block](/docs/ios/examples/routing-navigation/road-block.md): This example demonstrates how to use GEMKit in a UIKit application to set a road block ahead of the simulated position during navigation, forcing the engine to recalculate around the blocked segment.
- [Route Instructions](/docs/ios/examples/routing-navigation/route-instructions.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a route and display a detailed list of turn-by-turn instructions alongside any traffic events along the path.
- [Route Profile](/docs/ios/examples/routing-navigation/route-profile.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a pedestrian route with terrain profiling enabled and display interactive elevation, surface, road type, and steepness charts.
- [Simulate Route](/docs/ios/examples/routing-navigation/simulate-route.md): This example demonstrates how to use GEMKit in a UIKit application to calculate a route and simulate driving it at an accelerated speed with turn-by-turn voice guidance.
- [Alarms](/docs/ios/guides/alarms.md): In modern mobile applications, providing real-time notifications and alerts is crucial for ensuring a seamless user experience, especially in location-based services. The Maps SDK for iOS offers a robust alarm system that enables developers to monitor and respond to various events based on the user's location, speed, and interactions with geographical boundaries or landmarks.
- [Areas alarms](/docs/ios/guides/alarms/areas-alarms.md): Trigger operations when users enter or exit defined geographic areas using the AlarmContext.
- [Get started with Alarms](/docs/ios/guides/alarms/get-started-alarms.md): This guide explains how to set up and configure the alarm system to monitor geographic areas, routes, and receive notifications for various events.
- [Landmark and overlay alarms](/docs/ios/guides/alarms/landmark-and-overlay-alarms.md): This guide explains how to configure notifications when approaching specific landmarks or overlay items within a defined proximity.
- [Other alarms](/docs/ios/guides/alarms/other-alarms.md): Receive alerts for environmental changes such as entering or exiting tunnels, transitions between day and night, and country border crossings.
- [Speed warnings](/docs/ios/guides/alarms/speed-alarms.md): This guide explains how to configure speed limit monitoring and receive notifications about speed violations and speed limit changes.
- [Core](/docs/ios/guides/core.md): This section covers the core runtime entities used across the Maps SDK for iOS: geographic primitives, positions, landmarks, markers, overlays, routes, navigation instructions, traffic events, and image rendering APIs.
- [Base entities](/docs/ios/guides/core/base-entities.md): This page covers the fundamental building blocks of the iOS SDK: coordinates, paths, and geographic areas.
- [Images](/docs/ios/guides/core/images.md): The Maps SDK for iOS uses ImageObject for plain SDK images and UIKit-native UIImage rendering for display. Some APIs expose ImageObject so you can control rendering yourself, while navigation-oriented APIs render UIImage directly.
- [Landmarks](/docs/ios/guides/core/landmarks.md): A landmark is a rich point-of-interest entity represented by LandmarkObject. It combines location, metadata, media, categories, and store membership. Landmarks represent significant, categorized locations with rich metadata and structured context about a place.
- [Landmarks vs Markers vs Overlays](/docs/ios/guides/core/landmarks-markers-overlays.md): When building map features, choose the entity that matches your data lifecycle and interaction model.
- [Markers](/docs/ios/guides/core/markers.md): A marker is a visual geometry represented by MarkerObject. Markers are ideal for temporary annotations, shapes, user-defined graphics, and lightweight map overlays that are local to your app session.
- [Navigation Instructions](/docs/ios/guides/core/navigation-instructions.md): The iOS SDK provides real-time navigation guidance through NavigationInstructionObject. It exposes current street and road details, speed-limit context, remaining time and distance, lane guidance, and upcoming maneuvers during active navigation or simulation.
- [Overlays](/docs/ios/guides/core/overlays.md): An overlay is an additional map layer with data stored on Magic Lane servers, accessible in both online and offline modes. Overlays can be default or user-defined, and they support category hierarchies and downloadable offline data.
- [Positions](/docs/ios/guides/core/positions.md): This page covers position handling in iOS using PositionObject and PositionContext.
- [Routes](/docs/ios/guides/core/routes.md): A route represents a navigable path between two or more landmarks (waypoints), including distance, estimated time, and navigation instructions.
- [Traffic Events](/docs/ios/guides/core/traffic-events.md): The Maps SDK for iOS provides real-time traffic information about delays, incidents, and road restrictions that can affect routing and navigation.
- [Get started](/docs/ios/guides/get-started.md): The Magic Lane SDKs enable developers to build advanced navigation and mapping applications with minimal setup. The guides below walk you through creating an API key, integrating the SDK of your choice, building your first application, and following best practices for optimal performance.
- [Coding with AI](/docs/ios/guides/get-started/coding-with-ai.md): Use LLM-friendly documentation files and AI coding assistants to accelerate development with the Magic Lane Maps SDK for iOS.
- [Integrate the SDK](/docs/ios/guides/get-started/integrate-sdk.md): The Magic Lane Maps SDK for iOS is distributed as a Swift Package hosted on GitHub, making it easy to integrate directly into your Xcode projects using Swift Package Manager (SPM).
- [Maps SDK for iOS](/docs/ios/guides/introduction.md): The Maps SDK for iOS offers a powerful and comprehensive set of features that enable developers to integrate seamless mapping and navigation experiences into their applications
- [Maps](/docs/ios/guides/maps.md): This section covers map-first workflows in the Maps SDK for iOS: creating map views, camera and gesture control, and displaying landmarks, markers, overlays, routes, instructions, paths, and map styles.
- [Adjust map view](/docs/ios/guides/maps/adjust-map.md): The iOS SDK lets you control viewport framing, camera orientation, zoom, perspective, and coordinate transforms through MapViewController and MapViewPreferencesContext.
- [Display map items](/docs/ios/guides/maps/display-map-items.md): This section covers how to render and manage map entities in iOS: landmarks, markers, overlays, routes, route instructions, and paths.
- [Display landmarks](/docs/ios/guides/maps/display-map-items/display-landmarks.md): Learn how to filter, add, and highlight landmarks on the map.
- [Display markers](/docs/ios/guides/maps/display-map-items/display-markers.md): Learn how to add and style point, polyline, and polygon markers, including labeling and clustering behavior.
- [Display overlays](/docs/ios/guides/maps/display-map-items/display-overlays.md): Overlays provide enhanced, layered information on top of your base map. They offer dynamic, interactive, and customized data that adds contextual value to map elements.
- [Display paths](/docs/ios/guides/maps/display-map-items/display-paths.md): Learn how to render PathObject instances on the map using PathCollectionObject.
- [Display route instructions](/docs/ios/guides/maps/display-map-items/display-route-instructions.md): Learn how to focus the map on route instructions and show maneuver arrows during route visualization.
- [Display routes](/docs/ios/guides/maps/display-map-items/display-routes.md): Learn how to display routes on the map, assign the main route, style route rendering, and manage route labels.
- [Get started with maps](/docs/ios/guides/maps/get-started.md): Learn how to display a map view and work with MapViewController, the core iOS map runtime controller.
- [Interact with map](/docs/ios/guides/maps/interact-with-map.md): Use MapViewControllerDelegate, cursor selection APIs, and map-view preferences to handle user interactions, gestures, selections, and map render updates.
- [Styling](/docs/ios/guides/maps/styling.md): Learn how to customize map appearance using predefined styles or custom styles created in Magic Lane Map Studio.
- [Navigation](/docs/ios/guides/navigation.md): The Magic Lane iOS SDK offers developers a comprehensive solution for building turn-by-turn navigation systems within mobile applications. The SDK features critical tools like live guidance, offline support, and warning alerts (such as speed limits and traffic conditions). Real-time navigation adapts dynamically to the user's progress, notifying them of any route deviations and recalculating the path as needed. The SDK also supports a location simulator for testing navigation functionalities during app development.
- [Better route detection](/docs/ios/guides/navigation/better-route-detection.md): Monitor traffic conditions and automatically evaluate alternative routes for optimal navigation. This feature provides real-time route adjustments, reducing travel time and improving efficiency in dynamic traffic environments.
- [Get started with Navigation](/docs/ios/guides/navigation/get-started-navigation.md): This guide shows you how to implement turn-by-turn navigation in your iOS app using NavigationContext and NavigationContextDelegate.
- [Roadblocks](/docs/ios/guides/navigation/roadblocks.md): This guide explains how to add, manage, and remove roadblocks to customize route planning and navigation.
- [Add voice guidance](/docs/ios/guides/navigation/voice-guidance.md): Enhance navigation experiences with spoken instructions. This guide covers enabling the built-in SoundContext, managing voice settings, switching voices and languages, and integrating custom TTS playback using AVSpeechSynthesizer.
- [Offline](/docs/ios/guides/offline.md): The Maps SDK for iOS provides extensive offline functionality through its map download capabilities. Users can search for landmarks, calculate and navigate routes, and explore the map without requiring an active internet connection inside downloaded regions. The SDK also provides the ability to download content (maps, styles, or voices) and to manage downloaded content.
- [Introduction](/docs/ios/guides/offline/introduction.md): The Maps SDK for iOS provides offline functionality through map download capabilities.
- [Manage Content](/docs/ios/guides/offline/manage-content.md): Manage offline content through the Maps SDK for iOS.
- [Update Content](/docs/ios/guides/offline/update-content.md): The Maps SDK for iOS allows updating downloaded content to stay synchronized with the latest map data.
- [Positioning & Sensors](/docs/ios/guides/positioning.md): This section covers positioning workflows in the Maps SDK for iOS: data sources, live and custom positions, follow-position behavior, recorder setup, projection conversion, and camera-feed integration.
- [Background location](/docs/ios/guides/positioning/background-location.md): Learn how to enable location updates while your app is in background on iOS.
- [Camera feed](/docs/ios/guides/positioning/camera-feed.md): The SDK DataSourceContext provides access to camera frames for both live camera feeds and recorded logs.
- [Custom positioning](/docs/ios/guides/positioning/custom-positioning.md): Learn how to push custom positions into an external DataSourceContext and consume them through PositionContext.
- [Get started with positioning](/docs/ios/guides/positioning/get-started-positioning.md): Learn how to configure permissions and start receiving live position updates in iOS.
- [Projections](/docs/ios/guides/positioning/projections.md): Learn how to create projection objects and convert between coordinate systems using ProjectionContext.
- [Recorder](/docs/ios/guides/positioning/recorder.md): The Recorder module manages sensor data recording with configurable parameters through RecorderConfigurationObject. Key features include:
- [Sensors and data sources](/docs/ios/guides/positioning/sensors-and-data-sources.md): Learn how DataSourceContext provides live, playback, simulation, and external sensor streams for positioning workflows.
- [Show location on map](/docs/ios/guides/positioning/show-your-location-on-the-map.md): Learn how to follow the current position, tune follow-position behavior, and customize the position tracker on the map.
- [Public Transit Stops](/docs/ios/guides/public-transit-stops.md): This API provides access to public transport data including agencies, routes, stops, and trips. Fetch and explore real-time public transportation information from selected positions on the map.
- [Routing](/docs/ios/guides/routing.md): Routing functionality provides a robust solution for calculating, customizing, and analyzing routes for various transportation needs. You can calculate routes between a start and destination point, include intermediate waypoints for multi-stop routes, and determine areas accessible within a specific range.
- [Advanced features](/docs/ios/guides/routing/advanced-features.md): This guide covers advanced routing features including route ranges, path-based routes, public transit routing, and route export.
- [Get started with routing](/docs/ios/guides/routing/get-started-routing.md): This guide explains how to calculate routes, retrieve turn-by-turn instructions, access terrain profiles, traffic events, and detailed route information using NavigationContext and RoutePreferencesObject.
- [Route Bookmarks](/docs/ios/guides/routing/route-bookmarks.md): This guide explains how to store, manage, and retrieve route collections as bookmarks between application sessions using RouteBookmarksObject.
- [Handling Route Preferences](/docs/ios/guides/routing/route-preferences.md): This guide explains how to customize routes using preferences, configure vehicle profiles, and apply routing constraints for different transport modes.
- [Search](/docs/ios/guides/search.md): The SDK supports multiple search workflows through SearchContext, including free-text search, proximity search, category filtering, overlay search, route-based search, and guided address search.
- [Getting started with Search](/docs/ios/guides/search/get-started-search.md): The Maps SDK for iOS provides flexible search functionality for finding locations using text queries, coordinates, categories, landmark stores, and overlays:
- [Search & Geocoding features](/docs/ios/guides/search/search-geocoding-features.md): This guide explains how to convert coordinates to addresses and addresses to coordinates, work with hierarchical address search, build auto-suggestions, and search along routes with SearchContext.
- [Timezone service](/docs/ios/guides/timezone-service.md): The TimezoneContext class provides functionality for retrieving time zone information based on coordinates and a UTC timestamp, using built-in offline data.
- [Weather](/docs/ios/guides/weather.md): The Maps SDK for iOS provides weather capabilities through its WeatherContext class. With it, you can retrieve current conditions, hourly forecasts, and daily outlooks — including temperature, air quality, atmospheric pressure, wind speed, UV index, and more.
- [Base Entities](/docs/ios/guides/weather/base-entities.md): Weather-related data is organized into distinct classes, each designed to encapsulate specific weather information.
- [Weather Service](/docs/ios/guides/weather/weather-service.md): The WeatherContext class provides methods for retrieving current, hourly, and daily weather forecasts. Access the shared instance via WeatherContext.shared().