# Magic Lane - Maps SDK for TypeScript documentation


## Docs

- [Get Started with Sample Apps](/docs/typescript/examples/get-started-with-sample-apps.md): Explore the Maps SDK for TypeScript through interactive examples. These examples demonstrate key features and help you understand how to integrate maps into your web applications.
- [Maps & 3D Scene](/docs/typescript/examples/maps-3dscene.md): These examples demonstrates how to work with interactive maps using the Maps SDK for TypeScript.
- [Assets Map Styles](/docs/typescript/examples/maps-3dscene/assets-map-styles.md): This example demonstrates how to load and apply custom map styles from assets. It shows how to fetch a .style file and apply it to the map dynamically.
- [Center Area](/docs/typescript/examples/maps-3dscene/center-area.md): This example demonstrates how to center the map camera on geographic areas such as rectangles, circles, or polygons.
- [Center on Coordinates](/docs/typescript/examples/maps-3dscene/center-coordinates.md): This example demonstrates how to center the map camera on specific geographic coordinates with a custom zoom level.
- [Center Traffic](/docs/typescript/examples/maps-3dscene/center-traffic.md): This example demonstrates how to focus the map camera on traffic information and congestion areas.
- [Custom Position Icon](/docs/typescript/examples/maps-3dscene/custom-position-icon.md): This example demonstrates how to customize the position tracker icon on the map using the Maps SDK for TypeScript. It shows how to load a custom PNG image to replace the default position marker and follow the user's position.
- [Draw Roadblock](/docs/typescript/examples/maps-3dscene/draw-roadblock.md): This example demonstrates how to visualize road obstacles and blockages on the map.
- [Draw Shapes](/docs/typescript/examples/maps-3dscene/draw-shapes.md): This example demonstrates how to draw various geometric shapes on the map, including polygons, circles, and custom areas.
- [External Markers](/docs/typescript/examples/maps-3dscene/external-markers.md): This example demonstrates how to render custom markers using external rendering with the Maps SDK for TypeScript. It fetches data from the OpenChargeMap API and displays charging stations as interactive HTML markers.
- [Follow Position](/docs/typescript/examples/maps-3dscene/follow-position.md): This example demonstrates how to track and follow the user's real-time location on the map with smooth camera animations.
- [Hello Map](/docs/typescript/examples/maps-3dscene/hello-map.md): This example demonstrates how to create a basic interactive map using the Maps SDK for TypeScript.
- [Map Compass](/docs/typescript/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.
- [Map Gestures](/docs/typescript/examples/maps-3dscene/map-gestures.md): This example demonstrates how to detect and handle various touch gestures on the map, including pan, pinch, rotate, swipe, and more.
- [Map Perspective](/docs/typescript/examples/maps-3dscene/map-perspective.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 toward the horizon).
- [Map Selection](/docs/typescript/examples/maps-3dscene/map-selection.md): This example demonstrates how to select and interact with map objects such as markers, routes, and other features.
- [Multiview Map](/docs/typescript/examples/maps-3dscene/multiview-map.md): In this guide, you will learn how to display multiple interactive maps in one viewport.
- [Overlapped Maps](/docs/typescript/examples/maps-3dscene/overlapped-maps.md): This example demonstrates how to layer multiple map views on top of each other, creating overlay effects.
- [Projections](/docs/typescript/examples/maps-3dscene/projections.md): This example demonstrates how to work with different coordinate projection systems and convert between them.
- [Public Transport](/docs/typescript/examples/maps-3dscene/public-transport.md): This example demonstrates how to calculate and display public transit routes including walking segments, bus segments, and fare information.
- [Places & Search](/docs/typescript/examples/places-search.md): These resources cover diverse features and methods for location-based intelligence and search operations.
- [Address Search](/docs/typescript/examples/places-search/address-search.md): This example demonstrates how to perform guided address searches and display the results on an interactive map.
- [Display Cursor Street Name](/docs/typescript/examples/places-search/display-cursor-street-name.md): This example demonstrates how to display the name of the street at the cursor position when users tap on the map.
- [Location Wikipedia](/docs/typescript/examples/places-search/location-wikipedia.md): This example demonstrates how to retrieve and display Wikipedia information for landmarks using the Maps SDK.
- [Search Along Route](/docs/typescript/examples/places-search/search-along-route.md): This example demonstrates how to calculate a route, simulate navigation, and search for landmarks along the route path.
- [Search Category](/docs/typescript/examples/places-search/search-category.md): This example demonstrates how to search for landmarks filtered by specific categories (e.g., restaurants, hotels, gas stations).
- [Search Location](/docs/typescript/examples/places-search/search-location.md): This example demonstrates how to search for landmarks around a specific geographic location using coordinates.
- [Text Search](/docs/typescript/examples/places-search/text-search.md): This example demonstrates how to perform text-based searches for landmarks and display results on an interactive map.
- [What Is Nearby](/docs/typescript/examples/places-search/what-is-nearby.md): This example demonstrates how to discover all nearby landmarks around the user's current position or a default location.
- [Routing & Navigation Examples](/docs/typescript/examples/routing-navigation.md): Explore interactive examples demonstrating routing and navigation features of the Maps SDK for TypeScript. Each example includes a live demo that you can interact with directly in your browser.
- [Areas Alarms](/docs/typescript/examples/routing-navigation/areas-alarms.md): This example demonstrates how to monitor geographic areas and receive notifications when entering or exiting defined zones during navigation simulation.
- [Better Route Notification](/docs/typescript/examples/routing-navigation/better-route-notification.md): This guide will teach you how to get notified when a better route is detected during navigation.
- [Calculate Bike Route](/docs/typescript/examples/routing-navigation/calculate-bike-route.md): Calculate routes optimized for bicycle navigation with cycling-specific preferences.
- [Calculate Route](/docs/typescript/examples/routing-navigation/calculate-route.md): This example demonstrates how to create a web application that calculates a route between two locations and displays it on a map using Maps SDK for TypeScript.
- [Finger Route](/docs/typescript/examples/routing-navigation/finger-route.md): This example demonstrates how to draw a route by tapping or clicking on the map to place waypoints, then calculating and displaying a route through those points using the Maps SDK for TypeScript.
- [GPX Route](/docs/typescript/examples/routing-navigation/gpx-route.md): Import and display GPX route files on the map.
- [GPX Routing Thumbnail Image](/docs/typescript/examples/routing-navigation/gpx-routing-thumbnail-image.md): This example demonstrates how to import a GPX file, calculate a route from the path data, and capture a thumbnail image of the route displayed on the map.
- [Lane Instructions](/docs/typescript/examples/routing-navigation/lane-instructions.md): Display lane guidance to help users navigate complex intersections and highway exits.
- [Multi Map Routing](/docs/typescript/examples/routing-navigation/multimap-routing.md): This example demonstrates how to create and manage multiple map views simultaneously, calculating and displaying different routes on each map using the Maps SDK for TypeScript.
- [Navigate Route](/docs/typescript/examples/routing-navigation/navigate-route.md): In this guide, you will learn how to compute a route between a departure point and a destination point, render the route on an interactive map, and then navigate along the route with real GPS positioning.
- [Public Transit](/docs/typescript/examples/routing-navigation/public-transit.md): This example demonstrates how to calculate public transit routes, display route segments with transit types, and handle alternative route selection.
- [Range Finder](/docs/typescript/examples/routing-navigation/range-finder.md): This example demonstrates how to calculate and display reachable areas (range) from a selected landmark based on time or distance constraints using the Maps SDK for TypeScript.
- [Route Alarms](/docs/typescript/examples/routing-navigation/route-alarms.md): This example demonstrates how to calculate a route with overlay items, simulate navigation along it, and receive real-time alarm notifications when approaching hazards or points of interest.
- [Route Instructions](/docs/typescript/examples/routing-navigation/route-instructions.md): Learn how to retrieve and display turn-by-turn navigation instructions for a calculated route.
- [Route Profile](/docs/typescript/examples/routing-navigation/route-profile.md): In this guide you will learn how to display a map, calculate routes between multiple points, and show a detailed route profile with elevation data and terrain analysis.
- [Simulate Navigation](/docs/typescript/examples/routing-navigation/simulate-navigation.md): This example demonstrates how to simulate navigation along a calculated route. This is useful for testing navigation features without actually driving or moving.
- [Speed TTS Warning](/docs/typescript/examples/routing-navigation/speed-tts-warning.md): This example demonstrates how to integrate Text-to-Speech (TTS) voice warnings for speed limit changes during navigation using the Maps SDK for TypeScript with browser TTS capabilities.
- [Speed Watcher](/docs/typescript/examples/routing-navigation/speed-watcher.md): Monitor current speed and get warnings when exceeding speed limits.
- [Truck Profile](/docs/typescript/examples/routing-navigation/truck-profile.md): This example demonstrates how to create a TypeScript application that displays a truck profile and calculates routes using the Maps SDK. Users can modify truck parameters and visualize routes on the map.
- [Core](/docs/typescript/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/typescript/guides/core/base-entities.md): On this page, we present the simpler entities (coordinates, position, path, geographic areas), while in the following pages we cover the more complex ones (landmarks, markers, overlays, routes).
- [Landmarks](/docs/typescript/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/typescript/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/typescript/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/typescript/guides/core/navigation-instructions.md): The Maps SDK for TypeScript 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/typescript/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/typescript/guides/core/positions.md): The GemPosition and GemImprovedPosition classes provide a representation of geographical and movement data for web-based location systems. They include details like coordinates, speed, altitude, direction, and accuracy derived from the browser's Geolocation API, along with road-related metadata such as speed limits and modifiers. With support for position quality assessment and timestamped data, they are well-suited for navigation applications.
- [Routes](/docs/typescript/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/typescript/guides/core/traffic-events.md): The Maps SDK for TypeScript provides real-time information about traffic events, such as delays, which can occur in various forms.
- [Get started](/docs/typescript/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/typescript/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 TypeScript.
- [Create your first application](/docs/typescript/guides/get-started/create-first-app.md): This guide will walk you through the steps to create a simple web application that displays an interactive map using the Magic Lane Maps SDK for TypeScript.
- [Integrate the SDK](/docs/typescript/guides/get-started/integrate-sdk.md): Add the package
- [Internationalization](/docs/typescript/guides/get-started/internationalization.md): The Magic Lane SDK for TypeScript provides extensive multilingual and localization support, ensuring seamless integration for global applications. By supporting a wide range of localizations, the SDK helps applications meet internationalization standards, enhance user engagement, and reduce friction for end-users across different markets.
- [Usage Guidelines](/docs/typescript/guides/get-started/usage-guidelines.md): This page outlines the recommended usage guidelines for the Maps SDK for TypeScript. Adhering to these recommendations can enhance code reliability and help prevent issues that may arise from improper implementation.
- [Maps SDK for TypeScript](/docs/typescript/guides/introduction.md): The Maps SDK for TypeScript offers a powerful and comprehensive set of features that enable developers to integrate seamless mapping and navigation experiences into their web applications
- [Minimum requirements](/docs/typescript/guides/introduction/minimum-requirements.md): The Maps SDK for TypeScript enables the development of web-based mapping applications that run in modern browsers. Refer to the minimum requirements outlined below.
- [Location Wikipedia](/docs/typescript/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/typescript/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/typescript/guides/maps/adjust-map.md): The Maps SDK for TypeScript provides multiple ways to modify the map view, center on coordinates or areas, including `GemView` functionality for exploring different perspectives.
- [Display map items](/docs/typescript/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/typescript/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 LandmarkStoreCollection class:
- [Display markers](/docs/typescript/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/typescript/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/typescript/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/typescript/guides/maps/display-map-items/display-route-instructions.md): Instructions are represented as arrows on the map and can be displayed by using `GemMap.centerOnRouteInstruction(instruction, zoomLevel)`. To obtain a route's instructions, see the Route structure section. The following example iterates through all instructions of the first segment of a route and displays each one by centering:
- [Display routes](/docs/typescript/guides/maps/display-map-items/display-routes.md): Routes can be displayed on the map by using `MapViewPreferences.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 bMainRoute parameter, or by calling the MapViewRoutesCollection.mainRoute` setter.
- [Get started with maps](/docs/typescript/guides/maps/get-started.md): The Maps SDK for TypeScript delivers powerful mapping capabilities, enabling developers to effortlessly integrate dynamic map views into their web 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 GemMap class, offering a wide range of configurable options.
- [Interact with the map](/docs/typescript/guides/maps/interact-with-map.md): The Maps SDK for TypeScript 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.
- [Navigation](/docs/typescript/guides/navigation.md): The Navigation module enables turn-by-turn guidance along calculated routes, providing real-time instructions, voice guidance, and automatic route recalculation when deviating from the planned path. It offers comprehensive navigation features including lane guidance, speed limit warnings, and arrival notifications.
- [Better route detection](/docs/typescript/guides/navigation/better-route-detection.md): The Maps SDK for TypeScript 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.
- [Getting started with Navigation](/docs/typescript/guides/navigation/get-started-navigation.md): The Navigation module provides comprehensive turn-by-turn navigation capabilities, enabling real-time guidance along calculated routes. It includes features such as voice instructions, automatic route recalculation, lane guidance, and speed limit warnings.
- [Roadblocks](/docs/typescript/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/typescript/guides/navigation/voice-guidance.md): Voice guidance in the Maps SDK for TypeScript allows you to enhance navigation experiences with spoken instructions. This guide covers how to integrate custom playback using the onTextToSpeechInstruction callback with the browser's built-in Text-to-Speech capabilities.
- [Positioning & Sensors](/docs/typescript/guides/positioning.md): The Positioning module provides powerful tools for managing location data in your web app, enabling features like navigation, tracking, and location-based services. It offers flexibility by supporting both real GPS data (via browser Geolocation API) 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.
- [Custom positioning](/docs/typescript/guides/positioning/custom-positioning.md): The Maps SDK for TypeScript 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/typescript/guides/positioning/get-started-positioning.md): The Positioning module enables your web 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 browser's Geolocation API or from a custom data source, offering flexibility to suit diverse application needs.
- [Projections](/docs/typescript/guides/positioning/projections.md): Besides the Coordinates class, the Maps SDK for TypeScript provides a Projection class that represents the base class for different geocoordinate systems such as:
- [Sensors and data sources](/docs/typescript/guides/positioning/sensors-and-data-sources.md): This section provides an overview of how the Maps SDK for TypeScript 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/typescript/guides/positioning/show-your-location-on-the-map.md): The location of the device is shown by default using an arrow position tracker. If `setLiveDataSource` 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/typescript/guides/public-transit-stops.md): This API provides detailed access to public transport data including agencies, routes, stops, and trips. It is designed to integrate 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/typescript/guides/routing.md): The Routing module provides advanced route calculation capabilities, enabling efficient navigation between waypoints. It supports multiple route types (car, pedestrian, bicycle), customizable preferences (fastest, shortest, eco-friendly), and real-time traffic awareness. Advanced features include route alternatives, waypoint optimization, and custom routing constraints.
- [Advanced features](/docs/typescript/guides/routing/advanced-features.md): Compute route ranges
- [Getting started with Routing](/docs/typescript/guides/routing/get-started-routing.md): The Routing module provides powerful route calculation capabilities, enabling you to compute routes between multiple waypoints with various transportation modes and preferences. Whether you need the fastest route, the shortest distance, or an eco-friendly path, the SDK offers comprehensive routing functionality.
- [Handling Route Preferences](/docs/typescript/guides/routing/route-preferences.md): Before computing a route, we need to specify some route options.
- [Search](/docs/typescript/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/typescript/guides/search/get-started-search.md): The Maps SDK for TypeScript provides flexible and robust search functionality, allowing you to search for locations using text queries and coordinates:
- [Search & Geocoding features](/docs/typescript/guides/search/search-geocoding-features.md): The Maps SDK for TypeScript provides geocoding and reverse geocoding capabilities. Key features include:
- [Timezone service](/docs/typescript/guides/timezone-service.md): The TimezoneService provides functionality for managing and retrieving time zone information.
- [Create a React Native app](/docs/typescript/react-native/create-a-react-native-app.md): This guide walks you through creating a React Native project and running it on Android or iOS.
- [React Native Examples](/docs/typescript/react-native/examples.md): React Native is a popular framework for building mobile applications using JavaScript and React.
- [Hello World](/docs/typescript/react-native/examples/hello-world.md): This example demonstrates the simplest way to display a map in a React Native application.
- [Human Voice Navigation](/docs/typescript/react-native/examples/human-voice-navigation.md): This example calculates a multi-stop route, starts navigation simulation, and plays human voice instructions while updating the UI with turn and ETA details.
- [Map Download](/docs/typescript/react-native/examples/map-download.md): This example lists available offline map packages and lets the user download, pause, or delete them. It also shows download progress and status for each item.
- [Voice Download](/docs/typescript/react-native/examples/voice-download.md): This example lets users browse available human voice packages, download them, and display country flags for each voice.
- [React Native plugin](/docs/typescript/react-native/introduction.md): Built on top of the Magic Lane TypeScript SDK, the React Native plugin extends its core mapping capabilities with a native component for map rendering, providing full access to the same powerful features.
- [Plugin integration](/docs/typescript/react-native/plugin-integration.md): The Magic Lane Maps SDK for React Native is built on top of the TypeScript SDK, providing the same powerful mapping features with a native React Native component for rendering maps.