# Magic Lane - Maps SDK for Android documentation


## Docs

- [Get Started With Sample Apps](/docs/android/examples/get-started-with-sample-apps.md): Prerequisites
- [Maps & 3D Scene](/docs/android/examples/maps-3dscene.md): Example applications for the Maps SDK for Android are available on IssueTracker. You can clone the repository and launch the applications by following the setup instructions provided in the README file.
- [Apply Custom Map Style](/docs/android/examples/maps-3dscene/apply-custom-map-style.md): In this guide you will learn how to render an interactive map, and change the map style by applying a custom map style edited with, and downloaded from, the online editor.
- [Apply Map Style](/docs/android/examples/maps-3dscene/apply-map-style.md): This example demonstrates how to create an app that displays an interactive map with a non-default style.
- [Download A Map](/docs/android/examples/maps-3dscene/download-a-map.md): This example demonstrates how to list the road maps available on the server for download, how to download a map while indicating the download progress, and how to display the download’s finished status.
- [Hello Map](/docs/android/examples/maps-3dscene/hello-map.md): In this example you will learn how to render an interactive map centered on a desired location. The map is fully 3D, supporting pan, pinch-zoom, rotate and tilt.
- [Map Compass](/docs/android/examples/maps-3dscene/map-compass.md): This example demonstrates how to render a compass icon that displays the heading rotation of an interactive map. The compass indicates the direction where 0 degrees is north, 90 degrees is east, 180 degrees is south, and 270 degrees is west. You will also learn how to rotate the map back to its default north-up orientation.
- [Maps Perspective Change](/docs/android/examples/maps-3dscene/maps-perspective-change.md): This example demonstrates how to toggle the map view angle between 2D (vertical look-down at the map) and 3D (perspective, tilted map, looking towards the horizon).
- [Overlapped Maps](/docs/android/examples/maps-3dscene/overlapped-maps.md): This example demonstrates how to create an Android application that display overlapped maps, showcasing the ability to layer map views.
- [Social Event Voting](/docs/android/examples/maps-3dscene/social-event-voting.md): This example demonstrates how to create an app with an interactive map that allows users to vote and view social events, using the Maps SDK.
- [Social Report](/docs/android/examples/maps-3dscene/social-report.md): In this guide you will learn how to send a social report from within an app. An interactive map is displayed, and the social report is sent automatically as soon as the map is ready.
- [Places & Search](/docs/android/examples/places-search.md): This collection of articles showcases a comprehensive suite of precision-driven location and search techniques - instantly delivering accurate POI results for landmarks, restaurants, businesses, cities, neighborhoods, attractions, and specific addresses; enabling the discovery of nearby, departure-point, or destination-relevant places (for example, EV charging stations) with essential details such as pricing, hours of operation, and landmark information; and providing global data online or offline, all seamlessly embedded directly in the map for up-to-the-minute, reliable navigation every time.
- [Define Persistent Roadblock](/docs/android/examples/places-search/define-persistent-roadblock.md): In this guide you will learn how to render an interactively defined road block on an interactive map and fly to the road block.
- [Draw and Fly To Polyline](/docs/android/examples/places-search/draw-and-fly-to-polyline.md): In this guide you will learn how to render an interactive map, draw a polyline on the map and fly to the location of the polyline.
- [Favourites](/docs/android/examples/places-search/favourites.md): In this guide you will learn how to insert a landmark into the favourites, and also show to remove a landmark from the favourites.
- [Free Text Search](/docs/android/examples/places-search/free-text-search.md): In this guide you will learn how to do a text search and display them in a list.
- [Map Selection](/docs/android/examples/places-search/map-selection.md): <Media
- [Search Nearby](/docs/android/examples/places-search/search-nearby.md): In this guide you will learn how to search for points of interest (POIs) near the current location.
- [What's Nearby Category](/docs/android/examples/places-search/whats-nearby-category.md): In this guide you will learn how to search for points of interest (POIs) near the current location looking for a certain type of POIs, like gas stations.
- [Routing & Navigation](/docs/android/examples/routing-navigation.md): Easily find the best route to a desired destination with precise data and live traffic. Regardless whether your users are online or offline.
- [External Position Source Navigation](/docs/android/examples/routing-navigation/external-position-source-navigation.md): In this guide you will learn how to simulate navigation along a route defined by an external data source.
- [Lane Instructions Simulated Navigation](/docs/android/examples/routing-navigation/lane-instruction-simulated-navigation.md): In this guide you will learn how to includes lane instruction icons which appear at the bottom of the viewport whenever nearing an upcoming bifurcation, or branching, of the road.
- [Route Instructions](/docs/android/examples/routing-navigation/route-instructions.md): In this guide you will learn how to get the text instructions for a computed route.
- [Route Navigation](/docs/android/examples/routing-navigation/route-navigation.md): In this guide you will learn how to do real navigation along a computed route rendered on an interactive map, from the current position to a desired destination.
- [Route Simulation With Instructions](/docs/android/examples/routing-navigation/route-simulation-with-instructions.md): In this guide you will learn how to simulate navigation along a computed route rendered on an interactive map, from a departure position to a desired destination.
- [Route Terrain Profile](/docs/android/examples/routing-navigation/route-terrain-profile.md): In this guide you will learn how to obtain and display terrain statistics for a route, given the coordinates of the departure and destination points.
- [Routing On Map](/docs/android/examples/routing-navigation/routing-on-map.md): In this guide you will learn how to render an interactive map, compute and render a route on the map and fly to the route.
- [Search Along Route](/docs/android/examples/routing-navigation/search-along-route.md): In this guide you will learn how to compute and render a route on an interactive map, from a departure position to a desired destination.
- [Set TTS Language](/docs/android/examples/routing-navigation/set-tts-language.md): In this guide you will learn how to set or change the TTS (text to speech) voice instruction language.
- [Truck Profile](/docs/android/examples/routing-navigation/truck-profile.md): In this guide you will learn how to compute a route based on the accessibility given by the physical characteristics of a truck, such as height, weight, length, width and number of axles, and then render the route on the map.
- [Voice Downloading](/docs/android/examples/routing-navigation/voice-downloading.md): In this guide you will learn how to list all navigation instruction voices available on the server, indicating which are already downloaded, and download a voice.
- [Alarms](/docs/android/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 GemSDK 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/android/guides/alarms/areas-alarms.md): Another powerful use case is triggering operations the moment a user enters or exits a defined geographic area.
- [Get started with Alarms](/docs/android/guides/alarms/get-started-alarms.md): The alarm system within the GemSDK offers a range of monitoring and notification functionalities. It allows for the detection and management of different types of alarms, such as boundary crossings, speed limit violations, and landmark alerts. The system provides the ability to configure parameters like alarm distance, overspeed thresholds, and whether monitoring should occur even without a route being followed.
- [Landmark and overlay alarms](/docs/android/guides/alarms/landmark-and-overlay-alarms.md): The AlarmService can be configured to send notifications upon approaching specific landmarks or overlay items within a defined proximity. This behavior can be tailored to trigger notifications exclusively during navigation or simulation modes, or while freely exploring the map without a predefined route.
- [Other alarms](/docs/android/guides/alarms/other-alarms.md): The Maps SDK for Android provides advanced notification capabilities, enabling users to receive alerts for significant environmental changes. This includes notifications for entering and exiting tunnels, as well as transitions between day and night, based on the user's current location and time of year.
- [Speed warnings](/docs/android/guides/alarms/speed-alarms.md): The SDK provides features for monitoring and notifying users about speed limits and violations. You can configure alerts for when a user exceeds the speed limit, when the speed limit changes on the new road segment with respect to the previous, and when the user returns to a normal speed range (onNormalSpeed). The SDK also allows you to set customizable thresholds for speed violations, which can be adjusted for both city and non-city areas. These features help provide timely and relevant speed-related notifications based on the user's location and current speed.
- [Core](/docs/android/guides/core.md): The articles will guide you in working with landmarks and markers, providing a deeper understanding of predefined and user-defined points of interest, rich metadata, and dynamic annotations. Additionally, you’ll learn how to integrate layered map data through overlays and create navigable routes for various use cases. Finally, you’ll delve into real-time navigation system entities, capable of supporting turn-by-turn guidance and route simulation to enhance user experience.
- [Base entities](/docs/android/guides/core/base-entities.md): On this page, we present the simpler ones (coordinates, position, path, geographic areas), while in the following pages we cover the more complex ones (landmarks, markers, overlays, routes).
- [Images](/docs/android/guides/core/images.md): The images are represented in an abstract form which is not directly drawable on the UI. The responsible classes are Image, AbstractGeometryImage, LaneImage, SignpostImage, and RoadInfoImage.
- [Landmarks](/docs/android/guides/core/landmarks.md): A landmark is a predefined, permanent location that holds detailed information such as its name, address, description, geographic area, categories (e.g., Gas Station, Shopping), entrance locations, contact details, and sometimes associated multimedia (e.g., icons or images). It represents significant, categorized locations with rich metadata, providing structured context about a place.
- [Landmarks vs Markers vs Overlays](/docs/android/guides/core/landmarks-markers-overlays.md): When building a sophisticated mapping application, choosing the right type of object to use for your specific needs is crucial. To assist in making an informed decision, we compare the three core mapping entities in the table below:
- [Markers](/docs/android/guides/core/markers.md): A marker is a visual representation (such as an icon or a geometry, like a polyline or polygon) placed at a specific geographic location on a map to indicate an important point of interest, event, or location.
- [Navigation instructions](/docs/android/guides/core/navigation-instructions.md): The Maps SDK for Android 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.
- [Overlays](/docs/android/guides/core/overlays.md): An Overlay is an additional map layer, either default or user-defined, with data stored on Magic Lane servers, accessible in online and offline modes, with few exceptions.
- [Positions](/docs/android/guides/core/positions.md): The PositionData and ImprovedPostionData classes provide a comprehensive representation of geographical and movement data for GPS-based systems. They include details like coordinates, speed, altitude, direction, and accuracy, along with road-related metadata such as speed limits and modifiers. With robust support for position quality assessment and timestamped data, it is well-suited for navigation and sensor-driven applications.
- [Routes](/docs/android/guides/core/routes.md): A Route usually represents a navigable path between two or more landmarks (waypoints). It includes data such as distance, estimated time, and navigation instructions.
- [Traffic Events](/docs/android/guides/core/traffic-events.md): The Maps SDK for Android provides real-time information about traffic events, such as delays, which can occur in various forms.
- [Driver Behaviour](/docs/android/guides/driver-behaviour.md): The Driver Behaviour feature enables the analysis and scoring of a driver's behavior during a trip, identifying risky driving patterns and summarizing them with safety scores. This feature tracks both real-time and session-level driving events, such as harsh braking, cornering, or ignoring traffic signs, and evaluates overall risk using multiple criteria.
- [Get started](/docs/android/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/android/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 Android.
- [Create your first app](/docs/android/guides/get-started/create-your-first-app.md): This guide describes the steps to create a new Android application that uses the Maps SDK for Android.
- [Integrate the SDK](/docs/android/guides/get-started/integrate-sdk.md): This guide describes the steps to install the most recent version of the Maps SDK for Android and configure your Android app to use the SDK.
- [Usage guidelines](/docs/android/guides/get-started/usage-guildelines.md): Legal requirements
- [Maps SDK for Android](/docs/android/guides/introduction.md): The Maps SDK for Android offers a powerful and comprehensive set of features that enable developers to integrate seamless mapping and navigation experiences into their applications.
- [Minimum requirements](/docs/android/guides/introduction/minimum-requirements.md): Before commencing development with the Maps SDK for Android, it is critical to validate your environment against the minimum system requirements. Adhering to these specifications ensures baseline compatibility and facilitates optimal runtime performance in location-aware applications. Key factors include supported API levels, Java/Kotlin language features, OpenGL ES compatibility, and device memory configurations.
- [Location Wikipedia](/docs/android/guides/location-wikipedia.md): Landmarks can include Wikipedia data such as title, image title, URL, description, page summary, language, and more. To demonstrate how to retrieve Wikipedia information, we introduce the ExternalInfo class, which handles Wikipedia data.
- [Maps](/docs/android/guides/maps.md): Through this series, we’ll take you step-by-step into key concepts such as adjusting map views, interacting with maps using gestures, and implementing personalized styles. Additionally, you’ll discover how to handle map overlays, markers, routes, and navigation, all while ensuring a smooth and engaging user experience. Whether you’re a seasoned developer or new to mapping technology, this guide will empower you to build innovative, map-driven applications with ease.
- [Adjust the map view](/docs/android/guides/maps/adjust-map.md): The Maps SDK for Android provides multiple ways to modify the map view, center on coordinates or areas, including `MapView` functionality for exploring different perspectives.
- [Display map items](/docs/android/guides/maps/display-map-items.md): This collection of articles covers a wide range of features and techniques for displaying various elements on a map within a mobile application, including landmarks, markers, overlays, routes, instructions, and paths.
- [Display landmarks](/docs/android/guides/maps/display-map-items/display-landmarks.md): When displaying the map, we can choose what types of landmarks we want to display. Each landmark can have one or more LandmarkCategory. To selectively display specific categories of landmarks programmatically, you can use the addStoreCategoryId method provided by the LandmarkStoresCollection class:
- [Display markers](/docs/android/guides/maps/display-map-items/display-markers.md): The base class for the marker hierarchy is Marker. It encapsulates coordinates assigned to a specific part. Multiple coordinates can be added to the same marker and be separated into different parts. If no part is specified, the coordinates are added to a default part, indexed as 0. The coordinates are stored in a list-like structure, where you can specify their index explicitly. By default, the index is set to -1, meaning the coordinate will be appended to the end of the list.
- [Display overlays](/docs/android/guides/maps/display-map-items/display-overlays.md): Overlays are used to provide enhanced, layered information that adds contextual value to a base map, offering users dynamic, interactive, and customized data that can be visualized on top of other map elements.
- [Display paths](/docs/android/guides/maps/display-map-items/display-paths.md): Paths can be displayed by adding them into `MapViewPathCollection. The MapViewPathCollection is an iterable collection, having fields like size, add, remove, removeAt, getPathAt and getPathByName`.
- [Display route instructions](/docs/android/guides/maps/display-map-items/display-route-instructions.md): Instructions are represented as arrows on the map and can be displayed by using `MapView.centerOnRouteInstruction(instruction, zoomLevel, xy, animation, viewAngle)`. To obtain a route's instructions, see the Route structure section. The following example iterates through all instructions of a route and displays each one by centering:
- [Display routes](/docs/android/guides/maps/display-map-items/display-routes.md): Routes can be displayed on the map by using mapView.preferences?.routes?.add(route, isMainRoute). Multiple routes can be displayed at the same time, but only one is the main one, the others being treated as secondary. Specifying which one is the main route can be done when calling MapViewRoutesCollection.add() by passing true to the mainRoute parameter, or by calling the MapViewRoutesCollection.mainRoute setter.
- [Get started with maps](/docs/android/guides/maps/get-started.md): The Maps SDK for Android delivers powerful mapping capabilities, enabling developers to effortlessly integrate dynamic map views into their applications. Core features include embedding and customizing map views, controlling displayed locations, and fine-tuning map properties. At the center of the mapping API is the GEMSurfaceView class, which serves as the primary component for rendering maps and handling user interactions.
- [Interact with the map](/docs/android/guides/maps/interact-with-map.md): The Maps SDK for Android map view natively supports common gestures like pinch and double-tap for zooming. The table below outlines the available gestures and their default behaviors on the map.
- [Styling](/docs/android/guides/maps/styling.md): The appearance of the map can be tailored by applying different styles. You can either download a predefined map style using the `ContentStore` class, which offers a variety of ready-to-use styles, or create a custom style using Magic Lane Map Studio which you can download and configure. In this guide, we'll explore both methods in detail.
- [Navigation](/docs/android/guides/navigation.md): The Magic Lane Android 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/android/guides/navigation/better-route-detection.md): The Maps SDK for Android continuously monitors traffic conditions and automatically evaluates alternative routes to ensure optimal navigation. This feature enhances user experience by providing real-time route adjustments, reducing travel time, and improving overall efficiency, especially in dynamic traffic environments.
- [Get started with Navigation](/docs/android/guides/navigation/get-started-navigation.md): The Maps SDK for Android provides developers with comprehensive tools to build a robust turn-by-turn navigation system. This functionality enables applications to track the current device location relative to a predefined route and deliver real-time navigational guidance.
- [Roadblocks](/docs/android/guides/navigation/roadblocks.md): A roadblock is a user-defined restriction applied to a specific road segment or geographic area, used to reflect traffic disruptions such as construction, closures, or areas to avoid.
- [Add voice guidance](/docs/android/guides/navigation/voice-guidance.md): Voice guidance in the Maps SDK for Android allows you to enhance navigation experiences with spoken instructions. This guide covers how to enable built-in Text-to-Speech (TTS), manage voice settings, switch voices and languages, and integrate custom playback using the onNavigationSound callback for maximum flexibility.
- [Offline](/docs/android/guides/offline.md): The SDK provides extensive offline functionality through downloadable map regions. Once downloaded, users can search for landmarks, calculate and navigate routes, and explore the map - all without an active internet connection. The SDK also supports downloading and managing additional content such as maps and styles.
- [Introduction](/docs/android/guides/offline/introduction.md): The Maps SDK for Android 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.
- [Manage Content](/docs/android/guides/offline/manage-content.md): The Maps SDK for Android offers comprehensive functionality for managing offline content.
- [Update Content](/docs/android/guides/offline/update-content.md): The Magic Lane SDK allows updating downloaded content to stay synchronized with the latest map data. New map versions are released every few weeks.
- [Positioning & Sensors](/docs/android/guides/positioning.md): The Positioning module provides powerful tools for managing location data in your app, enabling features like navigation, tracking, and location-based services. It offers flexibility by supporting both real GPS data and custom location sources, allowing for dynamic and accurate position tracking. In addition, the Recorder module complements the Positioning capabilities by enabling the recording of sensor data. With customizable settings, it allows you to tailor the recording process for various data types, such as video, audio, or sensor information.
- [Background Location](/docs/android/guides/positioning/background-location.md): Some use cases require location access even when the app is in the background. In such cases, you'll need to configure the Android platform appropriately. The SDK supports this scenario, but platform permissions and services must be correctly set up for it to work.
- [Custom positioning](/docs/android/guides/positioning/custom-positioning.md): The Maps SDK for Android allows setting custom data source with the PositionService to dynamically manage and simulate location data. This approach allows for external or simulated positioning data, providing flexibility beyond traditional GPS signals, and is ideal for testing or custom tracking solutions.
- [Get started with positioning](/docs/android/guides/positioning/get-started-positioning.md): The Positioning module enables your application to obtain and utilize location data, serving as the foundation for features like navigation, tracking, and location-based services. This data can be sourced either from the device's GPS or from a custom data source, offering flexibility to suit diverse application needs.
- [Projections](/docs/android/guides/positioning/projections.md): Besides the Coordinates class, the Maps SDK for Android provides a Projection abstract class that represents the base class for different geocoordinate systems such as:
- [Recorder](/docs/android/guides/positioning/recorder.md): The Recorder module is a comprehensive tool designed for managing sensor data recording in the Android SDK.
- [Sensors and data sources](/docs/android/guides/positioning/sensors-and-data-sources.md): This section provides an overview of how the Maps Android SDK integrates with various sensors and external data sources to enhance map functionality and interactivity. From GPS and compass data to accelerometer readings and custom telemetry inputs, the SDK is designed to support a wide range of sensor-driven scenarios.
- [Show location on map](/docs/android/guides/positioning/show-your-location-on-the-map.md): The location of the device is shown by default using an arrow position tracker. If the data source has been successfully set and the required permissions were granted then the position tracker showing the current location should be visible on the map as an arrow.
- [Public Transit stops](/docs/android/guides/public-transit-stops.md): This API provides detailed access to public transport data including agencies, routes, stops, and trips. It integrates with interactive map-based applications using the Magic Lane SDK and allows developers to dynamically fetch and explore real-time public transportation information from selected positions on the map.
- [Routing](/docs/android/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. Additionally, the routing service allows you to retrieve turn-by-turn instructions, traffic event details, and estimate time of arrival (ETA) along with travel durations and distances. The system supports a variety of options such as computing terrain profiles for elevation data, displaying routes on a map, and handling public transit routes.
- [Advanced features](/docs/android/guides/routing/advanced-features.md): Compute route ranges
- [Get started with routing](/docs/android/guides/routing/get-started-routing.md): Here's a quick overview of what you can do with routing:
- [Handling RoutePreferences](/docs/android/guides/routing/route-preferences.md): Before computing a route, we need to specify some route options using the RoutePreferences class.
- [Search](/docs/android/guides/search.md): The SDK supports several search methods including text search, proximity search, and category-based search, with customizable preferences like fuzzy matching and distance limits. Additionally, users can search for custom landmarks or within overlays. For geocoding, the SDK provides reverse geocoding, converting geographic coordinates into comprehensive address details, and geocoding, which allows locating specific places based on address components. The SDK also offers integration with Wikipedia for location-based content, and auto-suggestions to dynamically generate search results while typing.
- [Getting started with Search](/docs/android/guides/search/get-started-search.md): The Maps SDK for Android provides a flexible and robust search functionality, allowing the search of locations using text queries and coordinates:
- [Search & Geocoding features](/docs/android/guides/search/search-geocoding-features.md): The Maps SDK for Android provides geocoding and reverse geocoding capabilities. Key features include:
- [Settings Service](/docs/android/guides/settings-service.md): The Magic Lane SDK for Android provides functionality for storing key-value pairs in permanent storage. This is managed via the SettingsService class.
- [Social reports](/docs/android/guides/social-reports.md): Social reports are user-generated alerts about real-time driving conditions or incidents on the road. These reports can include various types of information, such as accidents, police presence, road construction and more.
- [Timezone service](/docs/android/guides/timezone-service.md): The TimezoneService provides functionality for managing and retrieving time zone information.
- [This part is undergoing development](/docs/android/guides/todo.md): This section of the documentation is currently being developed and will be available soon. Please check back later for updates.
- [Weather](/docs/android/guides/weather.md): The Magic Lane Android SDK’s WeatherService class offers a comprehensive suite of weather capabilities. With it, you can retrieve current conditions, hourly forecasts, and daily outlooks - including temperature, air quality, atmospheric pressure, wind speed, UV index, and many more parameters.
- [Base Entities](/docs/android/guides/weather/base-entities.md): Weather-related functionalities are organized into distinct classes, each designed to encapsulate specific weather data. These include LocationForecast, Conditions, and WeatherParameter. This document provides a detailed explanation of each class and its purpose.
- [Weather Service](/docs/android/guides/weather/weather-service.md): The WeatherService class contains methods for getting the current, hourly and daily forecasts.