Magic Lane Maps SDK for C++ API Reference

Welcome to the complete API reference for the Magic Lane Maps SDK for C++. Explore classes and methods for 3D map rendering, turn-by-turn navigation, offline maps, real-time traffic, POI search, geocoding, custom styling, fleet optimization, and more.

Key Capabilities

Area	Classes
Maps & Rendering	gem::MapViewV2 , gem::IMapViewListener , gem::CanvasBufferRenderer
Search & Geocoding	gem::SearchService , gem::SearchPreferences , gem::GuidedAddressSearchService
Routing (incl. EV)	gem::RoutingService , gem::RoutePreferences , gem::Route , gem::RouteList
Navigation	gem::NavigationService , gem::INavigationListener , gem::NavigationInstruction
Markers & Overlays	gem::Marker , gem::MarkerCollection , gem::OverlayService , gem::OverlayItem
Styles & Theming	MapViewV2::preferences()
Offline Content	gem::ContentStore , gem::ContentStoreItem , gem::MapDownloaderService
Traffic & Weather	gem::TrafficReplay , gem::TrafficEvent , gem::weather::Service
Social Layers	gem::SocialOverlay , gem::SocialReportsOverlayInfo , gem::SocialLabelsOverlayInfo
Geofencing	gem::Geofence , gem::IGeofenceListener
Sensing	gem::NavigationService (position tracking)
Fleet / VRP	gem::vrp::Service , gem::vrp::dlv::Fleet , gem::vrp::rs::Fleet

Design Principles

ApiObject-style Services

Many high-level managers and views expose a consistent surface:

• Asynchronous operations with cancellation via ProgressListener — e.g. SearchService::search(...), RoutingService::calculateRoute(...), ContentStore::asyncGetStoreContentList(...), Geofence::addAreas(...), weather::Service::getForecast(...), SocialOverlay::report(...).
• Query state & telemetry via getTransferStatistics() on services that move data ( gem::SearchService , gem::RoutingService , gem::ContentStore , gem::MapDownloaderService , gem::NavigationService , gem::weather::Service , gem::TrafficReplay ).
• Listener/observer hooks for runtime updates: gem::INavigationListener , gem::IGeofenceListener , social overlay listeners, etc.

Shared model types glue the modules together:

• Places & search → gem::Landmark , gem::LandmarkList , gem::AddressInfo
• Routes & guidance → gem::Route , gem::RouteList , gem::RouteInstruction , gem::RouteTrafficEvent
• Map view & overlays → gem::MapViewV2 , gem::Marker , gem::MarkerCollection , gem::OverlayItem
• Areas & geometry → gem::GeographicArea , gem::Coordinates , gem::Projection

Tip: Long-running calls usually accept a ProgressListener and have a matching cancel(...) / cancel(...) to stop gracefully.

Quick Start

1. Activate & load content
   • gem::ActivationService — licensing and activation where the SDK flavor enforces it
   • gem::MapDownloaderService — download/update map packages
   • gem::ContentStore , gem::ContentStoreItem , gem::ContentUpdater — manage on-device content
2. Show a map
   • gem::MapViewV2 and listeners (gem::IMapViewListener)
   • Rendering helpers: gem::CanvasBufferRenderer , gem::RenderingUtils
3. Add overlays
   • Markers & groups: gem::Marker , gem::MarkerCollection , gem::MapViewMarkerCollections
   • Overlays: gem::OverlayService , gem::OverlayItem
4. Search & route
   • gem::SearchService (with gem::SearchPreferences ), guided address via gem::GuidedAddressSearchService
   • gem::RoutingService (with gem::RoutePreferences , EV helpers & models)
5. Navigate & react to live data
   • gem::NavigationService , gem::INavigationListener , gem::NavigationInstruction
   • Traffic & weather: gem::TrafficReplay , gem::TrafficEvent ; gem::weather::Service
   • Geofencing: gem::Geofence , gem::IGeofenceListener
   • Social: gem::SocialOverlay for community reports/labels

Component Interactions

MapViewV2 - the interactive canvas

Key methods:

• preferences() — view preferences (camera, gestures, layers)
• Camera helpers: centerOnArea(...), centerOnRoute(...), centerOnLocation(...), getOptimalRoutesCenterViewport(...), getCursorWgsPosition()
• Selection: cursorSelectionLandmarks(), cursorSelectionStreets(), cursorSelectionOverlayItems(), cursorSelectionTrafficEvents()
• Tracking: startTrackingPosition(...), stopTrackingPosition(), isTrackingPosition()
• Markers & overlays: via gem::MapViewMarkerCollections and gem::MapViewRouteCollection

Markers & Collections

• gem::Marker : rich shape constructors (coordinates, area, center+radius, segments). Common ops: getId(), getPartCount(), getCoordinates(...), update(...), add(...), delete(...).
• gem::MarkerCollection : group, style and display control — add(...), delete(...), hitTest(...) etc.
• gem::MapViewMarkerCollections : manage groups in a view (add/contains/hitTest, per-group settings).

SearchService - POI, text, and spatial queries

• search(...) variants (text, area, around position, along route/path)
• Details: searchLandmarkDetails(...)
• Control: cancelSearch(...)
• Telemetry: getTransferStatistics()

RoutingService - multi-criteria & EV routing

• calculateRoute(...)
• Road blocks: setRouteRoadBlock(...), resetRouteRoadBlocks()
• EV support: getEVCarModels(), getEVCarModel(int)
• Status & telemetry: getRouteStatus(...), isCalculationRunning(...), getTransferStatistics()

NavigationService - turn-by-turn guidance

• Lifecycle: see gem::NavigationService (e.g. start/stop/pause)
• Parameters: getNavigationParameters()
• Telemetry: getTransferStatistics()

ContentStore & MapDownloaderService - offline data

• gem::ContentStore : getLocalContentList(type), getStoreContentList(type), async queries, createContentUpdater(type), checkForUpdate(type), cancel(...), getTransferStatistics().
• gem::MapDownloaderService : startDownload(...), cancelDownload(), setMaxSquareKm(int), getTransferStatistics().

SocialOverlay - community reports & labels

• Read: getReportsOverlayInfo(), getLabelsOverlayInfo(), gem::SocialReportsOverlayInfo , gem::SocialLabelsOverlayInfo , gem::SocialReportsOverlayCategory
• Write: prepareReporting(...) → report(...) → confirmReport(...) / denyReport(...) / updateReport(...) / deleteReport(...)
• Discuss: addComment(...), registerReportListener(...)

Geofence - areas & proximity

• CRUD: addArea(...), addAreas(...), getAreas(...), removeAreas(...)
• Proximity: getProximityAreas(...)
• Monitoring: startMonitoring(...), stopMonitoring(...)
• Control: cancel(...)

Weather::Service - current, hourly, daily

• Queries: getCurrent(...), getForecast(...), getDailyForecast(days, ...), getHourlyForecast(hours, ...)
• Limits & telemetry: getMaxCoordinatesPerRequest(), getMaxDayForDailyForecast(), getMaxHoursForHourlyForecast(), getTransferStatistics()
• Control: cancel(...)

Fleet Optimization (VRP)

• Model & service: gem::vrp::Service , gem::vrp::ConfigurationParameters , gem::vrp::Territory , gem::vrp::Vehicle , constraints and gem::vrp::Route
• Delivery / Ride-sharing: gem::vrp::dlv::Fleet , gem::vrp::dlv::Driver , gem::vrp::dlv::Ride , gem::vrp::rs::Fleet , gem::vrp::rs::Driver , gem::vrp::rs::Rider , gem::vrp::rs::Ride

Examples

From search to navigation with MapView

// 1) Search
gem::SearchService search;
gem::LandmarkList pois;
search.search(pois, /*ProgressListener*/{}, "coffee",
              gem::RectangleGeographicArea(), gem::SearchPreferences());
 
// 2) Route
gem::RoutingService routing;
gem::RouteList routes;
routing.calculateRoute(routes, pois[0], /*destination*/, gem::RoutingPreferences(), /*ProgressListener*/{});
 
// 3) Display
gem::MapViewV2 map;
auto& groups = map.markerCollections();
auto groupId = groups.add("results");
groups.setRenderSettings(groupId, gem::MarkerCollectionRenderSettings());
for(auto& lm : pois) { groups.add(groupId, gem::Marker(lm.position())); }
map.centerOnRoute(routes[0], /*rc*/{}, /*animation*/{});
 
// 4) Navigate
gem::NavigationService nav;
nav.start(routes[0]);

Copyright © 2021-2026 Magic Lane International B.V.