syncfusion-aspnetcore-maps

# Implementing Syncfusion Maps for ASP.NET Core The Syncfusion Maps component is a powerful tool for visualizing geographical data using Scalable Vector Graphics (SVG). It supports GeoJSON data, multiple layers, map providers (Bing, Azure, OpenStreetMap), and rich interactive features like zooming, panning, tooltips, and selection. ## Table of Contents - [When to Use This Skill](#when-to-use-this-skill) - [Component Overview](#component-overview) - [Documentation and Navigation Guide](#documentation-and-navigation-guide) - [Getting Started and Installation](#getting-started-and-installation) - [Layers and GeoJSON Data](#layers-and-geojson-data) - [Data Binding and Population](#data-binding-and-population) - [Markers](#markers) - [Bubbles](#bubbles) - [Data Labels](#data-labels) - [Color Mapping](#color-mapping) - [Legend](#legend) - [Annotations](#annotations) - [User Interactions](#user-interactions) - [Map Providers Integration](#map-providers-integration) - [Advanced Features](#advanced-features) - [Quick Start Example](#quick-start-example) - [Basic Map with GeoJSON and Color Mapping](#basic-map-with-geojson-and-color-mapping) - [Map with Markers](#map-with-markers) - [API Reference](#api-reference) - [Maps Class](#maps-class) - [Core Properties (63 total)](#core-properties-63-total) - [Maps Events (28 total)](#maps-events-28-total) - [MapsLayer Class](#mapslayer-class) - [Key Properties of MapsLayer](#key-properties-of-mapslayer) - [MapsZoomSettings Class](#mapszoomsettings-class) - [Key Properties of MapsZoomSettings](#key-properties-of-mapszoomsettings) - [MapsShapeSettings Class](#mapsshapesettings-class) - [Key Properties of MapsShapeSettings](#key-properties-of-mapsshapesettings) - [MapsMarker Class](#mapsmarker-class) - [Key Properties of MapsMarker](#key-properties-of-mapsmarker) - [Related Classes (40+ classes available)](#related-classes-40-classes-available) - [Enumerations](#enumerations) - [ProjectionType](#projectiontype) - [MarkerType](#markertype) - [MapsTheme](#mapstheme) - [TooltipGesture](#tooltipgesture) - [LegendType](#legendtype) - [Common Patterns](#common-patterns) - [Pattern 1: Choropleth Map with Data Binding](#pattern-1-choropleth-map-with-data-binding) - [Pattern 2: Interactive Map with Zoom and Selection](#pattern-2-interactive-map-with-zoom-and-selection) - [Pattern 3: Multiple Data Layers](#pattern-3-multiple-data-layers) - [Pattern 4: Bing Maps Integration](#pattern-4-bing-maps-integration) - [Key Properties Reference](#key-properties-reference) - [Essential Properties](#essential-properties) - [Layer Configuration](#layer-configuration) - [Interaction Settings](#interaction-settings) - [Common Use Cases](#common-use-cases) - [Use Case 1: Sales Dashboard by Region](#use-case-1-sales-dashboard-by-region) - [Use Case 2: Store Locator](#use-case-2-store-locator) - [Use Case 3: Population Density Visualization](#use-case-3-population-density-visualization) - [Use Case 4: Election Results Map](#use-case-4-election-results-map) - [Use Case 5: Shipping Routes Visualization](#use-case-5-shipping-routes-visualization) - [Use Case 6: Weather Map Dashboard](#use-case-6-weather-map-dashboard) - [Use Case 7: Real Estate Property Map](#use-case-7-real-estate-property-map) - [Related Components](#related-components) - [Additional Resources](#additional-resources) ## When to Use This Skill Use the Syncfusion Maps component when you need to: - **Visualize geographical data** - Display country, state, or regional data on interactive maps - **Create choropleth maps** - Show data distribution using color mapping across regions - **Plot location markers** - Display points of interest, offices, stores, or custom locations - **Render bubble maps** - Visualize quantitative data with size-based bubbles on geographical locations - **Integrate map providers** - Use Bing Maps, Azure Maps, or OpenStreetMap as base layers - **Show custom shapes** - Render custom GeoJSON shapes for specific regions or areas - **Build interactive dashboards** - Create zoomable, pannable maps with tooltips and selection - **Display navigation routes** - Show navigation lines connecting different locations - **Overlay annotations** - Add custom HTML/text annotations on maps - **Create multi-layer visualizations** - Combine multiple data layers on a single map ## Component Overview **Key Capabilities:** - 📍 **Multiple Layers** - Support for unlimited layers and sublayers with independent configuration - 🗺️ **GeoJSON Support** - Load and render custom geographical shapes - 🌐 **Map Providers** - Integration with Bing Maps, Azure Maps, and OpenStreetMap - 🎨 **Color Mapping** - Visualize data with equal, range, and desaturation color schemes - 📌 **Markers & Bubbles** - Plot locations with customizable markers and size-based bubbles - 🏷️ **Data Labels** - Display shape names and data values with smart positioning - 🎯 **Interactivity** - Zoom, pan, tooltip, selection, and highlight features - 📊 **Legend** - Interactive legends for color mapping, markers, and bubbles - ✏️ **Annotations** - Custom HTML overlays at specific coordinates - 🌍 **Projections** - Support for 6 map projection types - 🖨️ **Export** - Print and export maps to PNG, JPEG, SVG, PDF formats - ♿ **Accessibility** - WCAG compliant with keyboard navigation and screen reader support ## Documentation and Navigation Guide ### Getting Started and Installation 📄 **Read:** [references/getting-started.md](references/getting-started.md) When user needs to: - Set up the Maps component for the first time - Install NuGet packages and configure dependencies - Add tag helpers and script references - Create a basic map with GeoJSON data - Understand the minimal setup requirements ### Layers and GeoJSON Data 📄 **Read:** [references/layers-and-geojson.md](references/layers-and-geojson.md) When user needs to: - Understand map layer architecture - Work with GeoJSON format and custom shapes - Add multiple layers or sublayers - Load GeoJSON from files or URLs - Configure layer visibility and ordering - Handle layer-specific settings ### Data Binding and Population 📄 **Read:** [references/data-binding.md](references/data-binding.md) When user needs to: - Bind data source to map shapes - Configure ShapeDataPath and ShapePropertyPath - Match data records to geographical shapes - Bind data from JSON, databases, or APIs - Update data dynamically - Transform data for visualization ### Markers 📄 **Read:** [references/markers.md](references/markers.md) When user needs to: - Add location markers to maps - Use different marker types (Circle, Image, Letter, Template) - Customize marker appearance (size, color, borders) - Position markers using latitude/longitude - Add marker tooltips and events - Implement marker clustering - Create custom marker templates ### Bubbles 📄 **Read:** [references/bubbles.md](references/bubbles.md) When user needs to: - Create bubble visualizations on maps - Size bubbles based on data values - Configure bubble colors and opacity - Set minimum and maximum bubble radius - Add bubble tooltips - Implement multiple bubble sets - Handle bubble selection ### Data Labels 📄 **Read:** [references/data-labels.md](references/data-labels.md) When user needs to: - Display labels on map shapes - Configure label positioning and alignment - Use smart label modes (Trim, Hide, None) - Customize label fonts and styling - Create template-based labels - Handle label intersections - Add labels to markers and bubbles ### Color Mapping 📄 **Read:** [references/color-mapping.md](references/color-mapping.md) When user needs to: - Apply colors to shapes based on data - Configure equal color mapping (value-to-color) - Set up range color mapping (min-max ranges) - Use desaturation color mapping (gradient opacity) - Create choropleth maps - Define custom color palettes - Handle accessibility and contrast ### Legend 📄 **Read:** [references/legend.md](references/legend.md) When user needs to: - Add legend to maps - Configure legend positioning and alignment - Enable interactive legend (toggle, highlight) - Customize legend shapes and text - Create legends for color mapping - Add legends for markers and bubbles - Implement legend paging for many items ### Annotations 📄 **Read:** [references/annotations.md](references/annotations.md) When user needs to: - Add custom HTML content to maps - Position annotations at specific coordinates - Create text or template-based annotations - Style and align annotations - Handle annotation z-index and layering - Add dynamic annotations - Create responsive annotations ### User Interactions 📄 **Read:** [references/user-interactions.md](references/user-interactions.md) When user needs to: - Enable zooming (mouse wheel, pinch, toolbar) - Configure panning features - Add tooltips with custom templates - Implement shape selection and multi-selection - Enable highlight on hover - Handle click events - Add navigation lines between locations - Set zoom levels and constraints ### Map Providers Integration 📄 **Read:** [references/map-providers.md](references/map-providers.md) When user needs to: - Integrate Bing Maps (Road, Aerial, Hybrid) - Set up Azure Maps with API keys - Use OpenStreetMap (OSM) tiles - Configure custom tile servers - Combine providers with GeoJSON layers - Handle provider authentication - Compare provider features and limitations ### Advanced Features When user needs to: - Render polygons with custom data - Add navigation lines with arrows - Print or export maps to images/PDF - Implement internationalization (i18n) - Configure localization (l10n) - Enable accessibility features - Implement state persistence - Use programmatic methods - Optimize performance - Migrate from EJ1 to EJ2 ## Quick Start Example ### Basic Map with GeoJSON and Color Mapping ```cshtml @using Newtonsoft.Json @using Syncfusion.EJ2.Maps @{ // Load GeoJSON data string geoJson = System.IO.File.ReadAllText("wwwroot/scripts/MapsData/WorldMap.json"); var worldMapData = JsonConvert.DeserializeObject(geoJson); // Load data source string dataJson = System.IO.File.ReadAllText("wwwroot/scripts/MapsData/population.json"); var populationData = JsonConvert.DeserializeObject(dataJson); // Define color mapping var colorMapping = new List<MapsColorMapping> { new MapsColorMapping { From = 0, To = 100000000, Color = "#C6E7F0", Label = "< 100M" }, new MapsColorMapping { From = 100000000, To = 500000000, Color = "#6AB7D6", Label = "100M - 500M" }, new MapsColorMapping { From = 500000000, To = 1500000000, Color = "#1A7FA0", Label = "> 500M" } }; var propertyPath = new[] { "name" }; } <ejs-maps id="maps" height="600px"> <e-maps-titlesettings text="World Population by Country"> <e-titlesettings-textstyle size="16px" fontWeight="500"></e-titlesettings-textstyle> </e-maps-titlesettings> <e-maps-legendsettings visible="true" position="Bottom"></e-maps-legendsettings> <e-maps-layers> <e-maps-layer shapeData="worldMapData" dataSource="populationData" shapeDataPath="Country" shapePropertyPath="propertyPath"> <e-layersettings-shapesettings fill="#E5E5E5" colorValuePath="Population" colorMapping="colorMapping"> </e-layersettings-shapesettings> <e-layersettings-tooltipsettings visible="true" valuePath="Country" template="#tooltipTemplate"> </e-layersettings-tooltipsettings> </e-maps-layer> </e-maps-layers> </ejs-maps> <div id="tooltipTemplate" style="background: white; padding: 12px; border-radius: 4px; box-shadow: 0 2px 8px rgba(0,0,0,0.15);"> <h4 style="margin: 0 0 8px 0; color: #333;">${Country}</h4> <div style="font-size: 14px;"> <div><strong>Population:</strong> ${Population}</div> <div><strong>Capital:</strong> ${Capital}</div> </div> </div> ``` ### Map with Markers ```cshtml @using Newtonsoft.Json @using Syncfusion.EJ2.Maps @{ var worldMapData = JsonConvert.DeserializeObject(System.IO.File.ReadAllText("wwwroot/scripts/MapsData/WorldMap.json")); var cities = new[] { new { Name = "New York", Latitude = 40.7128, Longitude = -74.0060, Population = "8.4M" }, new { Name = "Tokyo", Latitude = 35.6762, Longitude = 139.6503, Population = "13.9M" }, new { Name = "London", Latitude = 51.5074, Longitude = -0.1278, Population = "9.0M" }, new { Name = "Sydney", Latitude = -33.8688, Longitude = 151.2093, Population = "5.3M" } }; var tooltip = new MapsTooltipSettings { Visible = true, ValuePath = "Name" }; } <ejs-maps id="maps" height="600px"> <e-maps-zoomsettings enable="true" zoomFactor="2"></e-maps-zoomsettings> <e-maps-layers> <e-maps-layer shapeData="worldMapData"> <e-layersettings-shapesettings fill="#C3E6ED"></e-layersettings-shapesettings> <e-layersettings-markers> <e-layersettings-marker visible="true" dataSource="cities" shape="Circle" fill="#FF6347" height="15" width="15" tooltipSettings="tooltip"> </e-layersettings-marker> </e-layersettings-markers> </e-maps-layer> </e-maps-layers> </ejs-maps> ``` ## API Reference ### Maps Class The primary Maps component class with properties, methods, and events for controlling map behavior and appearance. **Namespace:** `Syncfusion.EJ2.Maps` **Assembly:** `Syncfusion.EJ2.dll` **[Official API Reference](https://help.syncfusion.com/cr/aspnetcore-js2/Syncfusion.EJ2.Maps.Maps.html)** #### Core Properties (63 total)