Overlays topic

Use the overlays module to discover, inspect and manage map overlay datasets and the items they expose. This system provides a consistent API for enumerating available overlay datasets, inspecting category hierarchies, reading preview metadata for individual overlay items, and controlling visibility or offline data download behaviour. It helps apps present rich, contextual map overlays (safety alerts, public-transport stops, social reports) and obtain typed preview information for UI panels and interactions.

• OverlayInfo: Represents metadata for an overlay dataset. Use it to obtain the overlay display name, unique identifier, icon and the top-level category hierarchy so your UI can present available overlays and drill into their categories.
• OverlayCategory: A node in an overlay's category tree. Use category objects to read display labels, icons, stable identifiers and nested subcategories when building category pickers or filtering overlay items.
• OverlayCollection: A read-only list of available overlay datasets. Retrieve an OverlayCollection from the service and use it to enumerate overlays, check presence by UID, and obtain OverlayInfo objects.
• OverlayMutableCollection: A modifiable collection variant used by services and preferences. Use it to add or remove overlays or single categories when you need to control which overlays are monitored or searchable.
• OverlayItem: Models a single item supplied by an overlay dataset. Use it to access coordinates, display name and image, parent overlay metadata, and to obtain typed preview parameters or extended preview data for detail panels. Is obtained via search results, map interactions or alarm triggers.
• OverlayItemParameters: Abstract base for typed preview data returned by overlay items. It standardises common metadata shapes and is specialised by concrete parameter classes for common overlay types. Is extended by PublicTransportParameters, SafetyParameters and SocialReportParameters.
• OverlayService: Service-level APIs for discovering available overlays and managing their enabled state or offline data grabbers. Use the service to retrieve the OverlayCollection, enable/disable overlays or categories and to start offline overlay downloads for supported overlays.
• CommonOverlayId: Enumeration of predefined overlay types (for example safety or public transport). Use these identifiers to check overlay item types or to enable/disable known overlay datasets.
• SocialOverlay, SocialReportsOverlayInfo, SocialReportsOverlayCategory, SocialReportListener, PredefinedCategoryParameterKeys, PredefinedReportParameterKeys: Crowd-sourced social reporting primitives used to prepare, submit, query and listen to user-generated route/road reports and overlay categories. Integrates with position services and map overlays for community-sourced incident data.

Overlay components work together to make overlays discoverable and actionable: the OverlayService exposes the set of available overlays as an OverlayCollection, each OverlayInfo provides category details via OverlayCategory objects, and individual OverlayItem instances give you both raw preview parameters and typed parameter objects (subclasses of OverlayItemParameters) for UI consumption. This design keeps discovery, configuration and item inspection separate so apps can efficiently list datasets, toggle visibility, and fetch detailed item data only when needed.

Use OverlayService to obtain the available overlays for the current map style, then enumerate the returned OverlayCollection to populate menus or settings. For item-level UX, prefer the typed preview parameter accessors: call the typed accessor on an OverlayItem to get a specific OverlayItemParameters subtype (for example PublicTransportParameters, SafetyParameters, or SocialReportParameters) and handle unknown/custom items via the raw parameter list. When you need persistent UI filters or alarm monitoring, use OverlayMutableCollection to add or remove overlays and categories so the rest of the SDK (map views, alarms) respects the chosen set.

Learn more about overlays: https://developer.magiclane.com/docs/flutter/guides/core/overlays