Support & Technical Documentation

Executive Summary

KML-KMZ-GeoJSON-MapViewer is a professional-grade custom visual for Microsoft Power BI that enables users to import, visualize, and interact with geospatial data directly within Power BI reports and dashboards. This visual bridges the gap between geographic information systems (GIS) and business intelligence by allowing users to display maps, routes, locations, territories, and spatial features alongside their data visualizations.

Key Features

•       Multi-Format Support – Import KML, KMZ, GeoJSON, and GPX files with full feature support for points, lines, and polygons.

•       Interactive Map Display – Professional mapping with pan, zoom, and more than 20 map tile layers (Google, Esri, OpenStreetMap, USGS, Carto, and more).

•       Layer Management – View, organize, search, and control visibility of all geospatial features through an intuitive layer panel.

•       Feature Customization – Customize colors for each feature, adjust line thickness (1–15 pixels), and fit the map to individual features.

•       Drawing Tools – Draw lines, polygons, rectangles, circles, and waypoints directly on the map with live length and area measurements.

•       Ruler Tool – Quick point-to-point distance measurement with support for metric and imperial units.

•       Analytics Panel – Live summary of visible feature counts, total lengths, total areas, and bound measure statistics.

•       File Append & Import – Append additional KML/KMZ files and import GeoJSON or GPX files to merge with the current layer set.

•       Smart Bookmarking – Fit map view to specific features with one click from the layer panel.

•       Automatic Persistence – KML/KMZ files, feature colors, visibility settings, map type, drawings, and all customizations automatically saved to the Power BI report.

•       Full Customization – Customize colors, toolbar visibility, button controls, panel fonts, and map settings to match your report theme.

•       Context Menu Integration – Right-click access to Power BI's export, spotlight, and focus features.

•       High-Contrast Support – Automatically adapts to Power BI's high-contrast accessibility mode.

•       Cross-Filter Integration – Clicking a feature fires a Power BI selection event to cross-filter other visuals on the page.

Support & Contact Information

Primary Contact

Developer: Abdalla Dabes, P.E, PSP, PMP

Email: AbdallaDabes@AbdallaAIsolutions.onmicrosoft.com

Organization: Abdalla AI Solutions

Support Services

Technical Support

•       KML, KMZ, GeoJSON, and GPX file upload and import issues

•       Map rendering and display problems

•       Feature visibility and layer panel issues

•       Persistence and settings problems

•       Drawing tool and ruler tool issues

•       Installation and configuration assistance

•       Leaflet map library compatibility

•       Performance optimization guidance

•       Map tile loading issues

•       Cross-filter and Power BI data binding issues

General Inquiries

•       Feature questions and clarifications

•       Best practices consultation

•       KML/KMZ/GeoJSON file preparation guidance

•       Implementation planning support

•       Compatibility verification

•       File size optimization

•       Geospatial data conversion

Feature Requests

•       Custom feature development

•       Integration requirements

•       Enhancement suggestions

•       Workflow improvements

•       Additional map type requests

•       Custom styling options

Response Times

Issue Type

Response Time

Critical Issues

1 business day acknowledgment

Technical Problems

2–3 business days resolution

General Questions

1–2 business days response

Feature Requests

3–5 business days evaluation

How to Contact Support

Email Support: AbdallaDabes@AbdallaAIsolutions.onmicrosoft.com

When contacting support, please include:

•       Power BI Desktop version (Help > About)

•       KML-KMZ-GeoJSON-MapViewer visual version

•       Description of the issue or question

•       Steps to reproduce the problem (if applicable)

•       Error messages or screenshots

•       File details: format (KML/KMZ/GeoJSON/GPX), file size (MB), number of features, geographic extent, source application

•       Environment: Power BI Desktop or Service, browser name and version, operating system

Support Hours

•       Standard Support: Monday – Friday, 9:00 AM – 5:00 PM (UAE Time)

•       Emergency Issues: Best-effort response within 24 hours

•       After Hours: Email submissions addressed on next business day

Additional Resources

KML / GIS Tools

•       Google Earth Pro (free KML editor)

•       QGIS (free, open-source GIS software)

•       ArcGIS Online (Esri web platform)

•       GPS Visualizer (online KML/GPX converter)

•       geojson.io (online GeoJSON editor and converter)

•       GPX to KML converters

Format Conversion

•       Google Earth (KMZ to KML)

•       QGIS (various GIS formats to KML, GeoJSON, GPX)

•       ogr2ogr (command-line GIS converter)

•       Online converters (MyGeodata, Aspose, Mapshaper)

Common Issues & Quick Solutions

KML/KMZ/GeoJSON/GPX file not uploading

•       Verify file is a valid KML, KMZ, GeoJSON, or GPX format.

•       Test KML/KMZ files in Google Earth first.

•       Test GeoJSON files at geojson.io.

•       Check for XML/JSON errors in the file structure.

•       Ensure file size is reasonable (<10 MB recommended for KML/KMZ).

Map does not appear after import

•       The file should load within a few seconds. If not, check the browser console (F12).

•       Refresh the visual or re-upload the file.

•       Verify features have valid WGS84 coordinates.

Layer names do not appear

•       Close and reopen the layer panel (click the Layers button twice).

•       Verify KML file has <name> tags, or GeoJSON features have a name property.

Features do not show on map

•       Check feature visibility in layer panel (eye icon should be open).

•       Verify coordinates are valid (latitude: -90 to 90, longitude: -180 to 180).

•       Click Fit All button to zoom to all features.

•       Check if feature colour matches the map background.

Drawings disappeared after reopening the report

•       Ensure the report was saved after drawings were created.

•       Drawings are persisted via Power BI's property storage and require at least one report save.

Settings do not persist after navigation

•       Ensure you are in edit mode, not view mode.

•       Settings only persist when the report is saved in edit mode.

Map tiles not loading

•       Check your internet connection.

•       Verify the network allows connections to tile servers (Google, Esri, OpenStreetMap, Carto, USGS).

•       Try switching map types in the tile-layer switcher.

•       Check firewall/proxy settings.

Layer panel not opening

•       Ensure Show Layer Panel is enabled in Format pane > Controls.

•       Click the Layers button (Layers) in the toolbar.

•       Ensure the toolbar is visible (Format pane > Appearance > Show Toolbar).

Toolbar hidden but buttons not showing

•       Buttons float over the map when the toolbar background is hidden.

•       Check Format pane > Appearance for individual button visibility toggles.

•       Try toggling Show Toolbar on then off again.

Context menu not appearing

•       Right-click anywhere in the visual (not on a button).

•       Try clicking on the map area specifically.

•       Check the browser console for JavaScript errors.

KML / GeoJSON File Optimization Guide

Recommended File Specifications

For best performance:

•       File Size: Under 10 MB for KML/KMZ; GeoJSON under 5 MB

•       Features: Fewer than 100 features per file recommended

•       Geometry: Simplified polygons and lines (fewer coordinate points)

•       Coordinate Precision: 5–6 decimal places (adequate for most use cases)

•       Structure: Clean XML/JSON with minimal nesting

File Size Guidelines

Size

Features

Formats

Use Case

< 1 MB

1–20

KML/KMZ/GeoJSON

Sales territories, store locations

1–5 MB

20–100

KML/KMZ/GeoJSON

Delivery routes, district boundaries

5–10 MB

100–500

KML/KMZ

Regional maps, detailed networks

> 10 MB

500+

KML/KMZ

Split into multiple files; simplify geometry

Geometry Simplification (QGIS)

1.     Vector > Geometry Tools > Simplify

2.     Tolerance: 0.0001 (adjust based on scale)

3.     Save as new KML or GeoJSON

Note: For large GPS tracks, enable Format pane > Performance > Simplify Lines and set Simplify Tolerance to 5–10 m for a significant performance improvement with no visible quality loss.

KML Structure Best Practices

A minimal, clean KML Placemark structure:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
<Placemark>
  <name>Store 1</name>
      <Point><coordinates>-122.08,37.42,0</coordinates></Point>
</Placemark>
  </Document>
</kml>

Troubleshooting Workflow

4.     Verify file is valid KML, KMZ, GeoJSON, or GPX. Check file size (<10 MB recommended). Test KML/KMZ in Google Earth; test GeoJSON at geojson.io.

5.     Confirm all features display correctly in the source application. Check feature names, descriptions, and that coordinates are correct.

6.     Simplify geometry if needed using QGIS or Mapshaper. Remove unnecessary metadata and save as a clean file.

7.     Update Power BI Desktop to the latest version. Clear the browser cache for Power BI Service. Restart the application.

8.     Try Power BI Service if Desktop fails, or test in a different browser (Chrome, Edge, Firefox). Verify network connectivity for map tiles.

9.     If the issue persists, email AbdallaDabes@AbdallaAIsolutions.onmicrosoft.com with all details, troubleshooting steps attempted, screenshots, and a sample file if possible.

Known Limitations

Limitation

Detail & Workaround

File Size

Very large files (>10 MB) may load slowly. Split into multiple files and simplify geometry.

Feature Count

500+ features may impact rendering performance. Group features or use multiple visuals.

Coordinate Systems

Only WGS84 (standard lat/lon) supported. Convert other projections before import.

Complex Geometry

Very complex polygons may render slowly. Simplify using QGIS or Mapshaper.

Map Tiles Offline

Requires internet connection for base map tiles. Features still render without tiles.

Mobile Support

Touch controls may be limited in Power BI Mobile. Best experience on desktop/web.

3D Features

KML altitude/3D features are not supported. Altitude data is ignored.

Network KML

Network links in KML are not supported. Flatten KML to a single file.

Custom KML Icons

Custom marker icons from KML are not rendered. Colour customisation is available instead.

GeoJSON CRS

Only WGS84 (EPSG:4326) GeoJSON supported. Re-project before import.

Supported File Elements

KML / KMZ — Fully Supported

✓ Point (Placemark with Point geometry)

✓ LineString (Placemark with LineString geometry)

✓ Polygon (Placemark with Polygon geometry)

✓ Feature names (<name> tag)

✓ Feature descriptions (<description> tag)

✓ Folders and document organisation

✓ KMZ compressed format

GeoJSON — Fully Supported

✓ Point, MultiPoint

✓ LineString, MultiLineString

✓ Polygon, MultiPolygon

✓ GeometryCollection

✓ FeatureCollection and Feature objects

✓ name / Name / NAME properties

GPX — Fully Supported

✓ Waypoints (<wpt>)

✓ Tracks and track segments (<trk> / <trkseg>)

✓ Routes (<rte>)

Partially Supported

•       Styles — the visual applies its own colours; KML style definitions are acknowledged but overridden.

•       Extended data — accessible in the feature popup but not displayed as separate fields.

Not Supported

✗ 3D features / altitude

✗ Network links

✗ Custom marker icons

✗ Ground overlays, photo overlays, screen overlays

✗ KML Tours

✗ Time-based animation

Version Information

Property

Value

Current Version

1.0.0

Last Updated

February 2026

API Version

Power BI Visual API 5.1.0

Map Library

Leaflet 1.9.4

Compatibility

✓ Power BI Desktop (latest version recommended)

✓ Power BI Service (all modern browsers)

✓ Windows 10 / 11

✓ macOS (Power BI Service)

✓ Chrome, Edge, Firefox, Safari

Tile Layer Sources

✓ Google Road, Satellite, Hybrid, Terrain

✓ Esri World Street, Imagery, Topographic, Terrain, National Geographic, Ocean, Physical, Dark Gray, Light Gray

✓ OpenStreetMap Humanitarian, CyclOSM, OpenTopoMap

✓ Carto Positron, Dark Matter, Voyager

✓ USGS US Topo, US Imagery, US Imagery Topo

Frequently Asked Questions (FAQ)

What file formats are supported?

KML (.kml), KMZ (.kmz), GeoJSON (.geojson / .json), and GPX (.gpx). KMZ is compressed KML.

What is the maximum file size?

No hard limit. Files up to the configured Max Persist Size (default 100 MB) are saved permanently in the report. Larger files remain for the current session and must be re-uploaded next time.

Do files persist when I navigate away?

Yes. Files within the Max Persist Size limit are automatically saved with the Power BI report and restored on the next load.

Can I load more than one file?

Yes. Use Tools > Append KML/KMZ File to merge additional KML/KMZ files, or Tools > Import GeoJSON / GPX for those formats. The merged feature set is persisted.

Can I edit KML files within the visual?

You can customise colours, visibility, and draw annotations, but cannot edit geometry or feature properties. Use Google Earth, QGIS, or geojson.io for editing.

Why do I not see map tiles?

Map tiles require an internet connection. Features will still render without tiles, but the base map will be absent.

How do I report bugs or request features?

Email AbdallaDabes@AbdallaAIsolutions.onmicrosoft.com with a description, Power BI version, visual version, screenshots, and a sample file if applicable.

Changelog

Version 1.0.0 — February 2026

•       Initial release

•       KML, KMZ, GeoJSON, and GPX file support

•       Points, lines, and polygons rendering with accurate projections

•       Interactive layer panel with search, visibility toggles, colour picker, and fit-to-feature

•       Drawing tool: lines, polygons, rectangles, circles, and waypoints with live measurements

•       Ruler tool for quick point-to-point distance measurement

•       Analytics panel with feature statistics and measure summaries

•       File append and multi-format import (GeoJSON, GPX)

•       Go-to-coordinates with decimal degrees and DMS support

•       Coordinate readout overlay

•       Keyboard shortcuts for all major functions

•       20+ base-map tile layers

•       Automatic persistence for files, drawings, settings, colours, and visibility

•       Power BI cross-filter and tooltip integration

•       Measure and tooltip data-role bindings

•       High-contrast accessibility mode support

•       Customisable toolbar, layer panel, and feature panel

Click here to download the manual