KML/KMZ Viewer for Microsoft Power BI
Technical Documentation and Feature Specification
Executive Summary
The KML/KMZ Viewer 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 and KMZ files with full feature support for points, lines, and polygons
Interactive Map Display - Professional mapping with pan, zoom, and multiple map type options (Street, Satellite, Terrain, Google Satellite, Google Hybrid)
Layer Management - View, organize, and control visibility of all geospatial features through an intuitive layer panel
Feature Customization - Customize colors for each feature, adjust line thickness (1-10 pixels), and fit map to individual features
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, and all customizations automatically saved
Full Customization - Customize colors, toolbar visibility, button controls, and map settings to match your report theme
Context Menu Integration - Right-click access to Power BI's export, spotlight, and focus features
Conclusion
The KML/KMZ Viewer visual represents a comprehensive solution for integrating geospatial content with business intelligence workflows. Through its combination of intuitive map controls, layer management features, and automatic persistence, it enables organizations to include essential location-based data within their Power BI reports while maintaining seamless user experience and data preservation across sessions.
Support & Contact Information
Get Help and Technical Support
Primary Contact
Developer: Abdalla Dabes, P.E, PSP, PMP
Email: AbdallaDabes@AbdallaAIsolutions.onmicrosoft.com
Organization: Abdalla AI Solutions
Support Services
Technical Support
• KML/KMZ file upload and import issues
• Map rendering and display problems
• Feature visibility and layer panel issues
• Persistence and settings problems
• Installation and configuration assistance
• Leaflet map library compatibility
• Performance optimization guidance
• Map tile loading issues
General Inquiries
• Feature questions and clarifications
• Best practices consultation
• KML/KMZ 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
• 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 Viewer visual version
• Description of the issue or question
• Steps to reproduce the problem (if applicable)
• Error messages or screenshots
• KML/KMZ file details:
- File format (KML or KMZ)
- File size (in MB)
- Number of features (points, lines, polygons)
- Geographic extent/coverage area
- Source of KML file (Google Earth, QGIS, ArcGIS, etc.)
• Browser/environment information:
- Power BI Desktop or Service
- Browser name and version
- Operating system
- Whether features persist or show correctly after navigation
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 will be addressed on next business day
Additional Resources
Documentation Updates
Check regularly for updated guides and troubleshooting tips
Community Support
For general Power BI questions, refer to the Microsoft Power BI Community forums
KML/KMZ Tools
• Google Earth Pro (free KML editor)
• QGIS (free, open-source GIS software)
• ArcGIS Online (Esri web platform)
• GPS Visualizer (online KML converter)
• GPX to KML converters
Format Conversion
• Google Earth (KMZ to KML)
• QGIS (various GIS formats to KML)
• ogr2ogr (command-line GIS converter)
• Online converters (MyGeodata, Aspose)
Common Issues & Quick Solutions
KML/KMZ file not uploading
• Verify file is valid KML or KMZ format
• Test file in Google Earth first
• Check for XML errors in KML structure
• Ensure file size is reasonable (<10MB recommended)
Map doesn't appear after import
• File should load within 1 second - if not, check browser console (F12)
• Refresh the visual
• Try re-uploading the file
• Verify features have valid coordinates
Layer names don't appear
• Close and reopen layer panel (click Layers button twice)
• Names should appear immediately - if not, check console for errors
• Verify KML file has <name> tags for features
Features don't 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 color matches map background
Settings don't persist after navigation
• Ensure you're in edit mode, not view mode
• Settings only persist when report is in edit mode
• Check that you've saved the Power BI report after changes
Map tiles not loading
• Check internet connection
• Verify network allows connections to OpenStreetMap and Google tile servers
• Try switching map types (Street, Satellite, Terrain)
• Check firewall/proxy settings
Layer panel not opening
• Ensure "Show Layer Panel" is enabled in Format pane > Controls
• Click the Layers button (📂) in toolbar
• Check that toolbar is visible (Format pane > Appearance > Show Toolbar)
Colors not changing
• Click color picker next to feature in layer panel
• Changes should apply immediately
• Verify feature is visible (eye icon open)
• Check that map has rendered correctly
Line thickness not applying
• Adjust in Format pane > Appearance > Line Thickness (1-10)
• Changes apply immediately to all lines and polygon borders
• Navigate away and return to verify persistence
Toolbar hidden but buttons not showing
• Buttons should float over map when toolbar is hidden
• Check Format pane > Appearance > Show Layers Button and Show New Button
• Ensure settings are ON
• Try toggling Show Toolbar ON then OFF again
Context menu not appearing
• Right-click anywhere in the visual
• Ensure you're not clicking on a button or interactive element
• Try clicking on the map area specifically
• Check browser console for JavaScript errors
KML/KMZ File Optimization Guide
Recommended File Specifications
For Best Performance:
• File Size: Under 10MB
• Features: Less than 100 features per file
• Geometry: Simplified polygons and lines (fewer points)
• Coordinate Precision: 5-6 decimal places (adequate for most uses)
• Structure: Clean XML with minimal nesting
File Size Guidelines:
File Type | Size | Features | Use Case
----------|------|----------|----------
Small | <1MB | 1-20 | Sales territories, store locations
Medium | 1-5MB| 20-100 | Delivery routes, district boundaries
Large | 5-10MB|100-500 | Regional maps, detailed networks
Very Large| >10MB|500+ | Split into multiple files
Feature Optimization
Simplify Geometry:
Use QGIS or online tools to reduce polygon/line complexity
Example QGIS simplification:
1. Vector > Geometry Tools > Simplify
2. Tolerance: 0.0001 (adjust based on scale)
3. Save as new KML
Reduce Coordinate Precision:
• Latitude/Longitude: 5-6 decimal places
• Example: 25.276987 instead of 25.27698700000000
• Use text editor or Python script to clean up
Remove Unnecessary Data:
• Delete unused extended data fields
• Remove descriptions if not needed
• Strip out Google Earth specific styles (visual will apply its own)
KML Structure Best Practices:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>My Locations</name>
<Placemark>
<name>Store 1</name>
<description>Description here</description>
<Point>
<coordinates>-122.0856545755255,37.42243077405461,0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
```
Troubleshooting Workflow
Step 1: Verify File Specifications
• Check file is valid KML or KMZ
• Verify file size (recommend <10MB)
• Test file opens in Google Earth
• Check for XML syntax errors
Step 2: Test in Google Earth
• Open file in Google Earth Pro
• Verify all features display correctly
• Check feature names and descriptions
• Confirm coordinates are correct
Step 3: Simplify if Needed
• Use QGIS to simplify complex geometry
• Reduce number of features if very large
• Remove unnecessary metadata
• Save as clean KML
Step 4: Check Power BI Environment
• Update Power BI Desktop to latest version
• Clear browser cache (for Power BI Service)
• Restart Power BI application
• Test in different browser if using Power BI Service
Step 5: Test in Different Environments
• Try Power BI Service (web) if Desktop fails
• Test in different browser (Chrome, Edge, Firefox)
• Check on different computer if available
• Verify network connectivity for map tiles
Step 6: Contact Support
• If issue persists, email with details above
• Include all troubleshooting steps attempted
• Attach screenshots or error messages
• Provide sample KML file if possible
Known Limitations
File Size
• Limitation: Very large files (>10MB) may load slowly
• Workaround: Split into multiple files; simplify geometry; reduce features
Feature Count
• Limitation: 500+ features may impact performance
• Workaround: Group features; use multiple visuals; simplify data
Coordinate Systems
• Limitation: Only WGS84 (standard lat/lon) supported
• Workaround: Convert other projections to WGS84 before import
Complex Geometry
• Limitation: Very complex polygons may render slowly
• Workaround: Simplify geometry using QGIS or other tools
Map Tiles
• Limitation: Requires internet connection for map display
• Workaround: Features still render, just no base map tiles offline
Mobile Support
• Limitation: Touch controls may be limited in Power BI Mobile
• Workaround: Best experience on desktop/web; use in view-only mode on mobile
3D Features
• Limitation: KML altitude/3D features not supported
• Workaround: Use 2D features only; altitude data ignored
Network KML
• Limitation: Network links in KML not supported
• Workaround: Flatten KML to single file with all features
Custom Icons
• Limitation: Custom marker icons from KML not used
• Workaround: Visual uses default markers; color customization available
Supported KML Elements
Fully Supported:
✓ Point (Placemark with Point geometry)
✓ LineString (Placemark with LineString geometry)
✓ Polygon (Placemark with Polygon geometry)
✓ MultiGeometry (multiple features in one Placemark)
✓ Feature names (<name> tag)
✓ Feature descriptions (<description> tag)
✓ Folders and organization
✓ KMZ compressed format
Partially Supported:
~ Styles (visual applies its own colors)
~ Extended data (accessible in popup but not displayed separately)
Not Supported:
✗ 3D features (altitude ignored)
✗ Network links
✗ Custom icons
✗ Ground overlays
✗ Photo overlays
✗ Screen overlays
✗ Tours
✗ Time-based animation
Support Commitment
We are committed to providing responsive, professional support to ensure your success with the KML/KMZ Viewer visual. Our goal is to resolve technical issues quickly and help you maximize the value of your investment in our solution.
Our Promises:
✓ Timely responses to all inquiries
✓ Expert guidance on KML/KMZ optimization
✓ Continuous improvement based on feedback
✓ Regular updates and enhancements
✓ Comprehensive documentation and resources
✓ Geospatial expertise and GIS knowledge
For urgent matters or time-sensitive projects, please indicate the priority level in your email subject line (e.g., "URGENT: KML Viewer Issue").
Version Information
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)
✓ Modern browsers: Chrome, Edge, Firefox, Safari
Map Tile Sources:
✓ OpenStreetMap (Street Map)
✓ Esri World Imagery (Satellite)
✓ Google Satellite
✓ Google Hybrid
✓ OpenTopoMap (Terrain)
Changelog
Version 1.0.0 (February 2026)
• Initial release
• KML and KMZ file support
• Points, lines, and polygons rendering
• Interactive layer panel with feature list
• Feature visibility toggles
• Color customization per feature
• Line thickness control (1-10 pixels)
• Multiple map types (5 options)
• Fit to feature functionality
• Fit to all features
• Automatic persistence for files, settings, colors, and visibility
• Map type selection persistence
• Customizable toolbar
• Independent button controls
• Context menu integration
• Touch device support
• Comprehensive Format pane settings
• Layer panel customization (width, font, font size)
• Map control toggles (zoom, pan, layer switcher)
Best Practices for Implementation
Data Preparation:
1. Test KML in Google Earth before importing
2. Keep files under 10MB for best performance
3. Use meaningful feature names
4. Include descriptions for important features
5. Simplify complex geometry
6. Use KMZ compression for files >1MB
Visual Configuration:
1. Set appropriate line thickness for your map scale
2. Choose map type that best displays your data
3. Customize colors to match your report theme
4. Configure layer panel width based on name length
5. Hide unnecessary controls for cleaner appearance
6. Enable/disable features based on user needs
Report Design:
1. Size visual appropriately (minimum 500x400 pixels recommended)
2. Allow space for layer panel if used
3. Consider color contrast with background
4. Test on different screen sizes
5. Provide instructions for users if needed
6. Document data sources and update frequency
Performance:
1. Split very large datasets into multiple files
2. Use simplified geometry for large areas
3. Consider feature count limits
4. Test performance before publishing
5. Monitor report load times
6. Optimize KML structure
Security:
1. Review KML content before uploading
2. Follow organizational data policies
3. Use Power BI security features (RLS, permissions)
4. Don't embed sensitive location data without authorization
5. Consider data classification requirements
6. Document content and approvals
Training Resources
Getting Started Guide:
• Installation instructions
• First KML import walkthrough
• Basic map navigation
• Layer panel overview
User Training Topics:
• How to prepare KML/KMZ files
• Using the layer panel
• Customizing feature colors
• Adjusting line thickness
• Switching map types
• Using bookmarks (fit to feature)
• Understanding persistence
• Troubleshooting common issues
Administrator Topics:
• Installation and deployment
• Security considerations
• Performance optimization
• User support procedures
• File size management
• Network requirements
Advanced Topics:
• KML file optimization
• Complex geometry handling
• Multi-file strategies
• Custom workflows
• Integration with other visuals
• Publishing best practices
Frequently Asked Questions (FAQ)
Q: What file formats are supported?
A: KML (.kml) and KMZ (.kmz) files. KMZ is compressed KML.
Q: What's the maximum file size?
A: No hard limit, but we recommend keeping files under 10MB for optimal performance. Files can be larger but may load more slowly.
Q: Do my files persist when I navigate away?
A: Yes! Files under 30MB are automatically saved with your Power BI report. Larger files remain for the session but may need re-upload.
Q: Can I edit KML files within the visual?
A: You can customize colors and visibility, but cannot edit geometry or feature properties. Use Google Earth or QGIS for editing.
Q: Why don't I see map tiles?
A: Map tiles require internet connection. If offline, features will still render but without base map imagery.
Q: Can I use custom map tiles or layers?
A: Currently limited to provided map types (Street, Satellite, Terrain, Google Satellite, Google Hybrid). Custom tile sources may be added in future versions.
Q: How do I create KML files?
A: Use Google Earth, QGIS, ArcGIS, or GPS Visualizer. Many GIS tools can export to KML format.
Q: Why are my feature names not showing?
A: Ensure your KML file includes <name> tags for each Placemark. Close and reopen the layer panel if needed.
Q: Can I display multiple KML files?
A: Currently one file per visual instance. Use multiple visuals or combine KML files externally.
Q: Does the visual work offline?
A: Features load from saved KML, but map tiles require internet. The visual works offline with features visible but no base map.
Q: How do I report bugs or request features?
A: Email AbdallaDabes@AbdallaAIsolutions.onmicrosoft.com with details, screenshots, and sample files if applicable.
Thank you for choosing KML/KMZ Viewer for Power BI! We're committed to your success with geospatial data visualization.