Leaflet Map Visualization Plugin

Create beautiful, interactive maps from your data files with automatic marker clustering, custom styling, and filtering capabilities.

Features

• Multiple Data Sources: Load data from JSON or CSV files
• Marker Clustering: Automatic clustering for better performance with large datasets
• Custom Styling: Color markers by property values with customizable palettes
• Interactive Popups: Display detailed information for each data point
• Filtering: Filter data by any property (numeric ranges, text matching)
• Search: Find specific locations by name or property values
• Heatmaps: Generate heatmap visualizations for density analysis
• HTML Export: Generate standalone HTML files that work offline
• Responsive Design: Maps work on desktop and mobile devices

Installation

# Using pets CLI
pets add leaflet

# Or install via npm
npm install @openpets/leaflet

Configuration

Environment Variables (Optional)

# Custom output directory for generated maps
LEAFLET_OUTPUT_DIR=/path/to/output

# Default map tile provider
LEAFLET_DEFAULT_TILES=openstreetmap

Tile Providers

The plugin supports multiple map tile providers:

• openstreetmap - Default, free, community-maintained
• cartodb-light - Clean, light theme (great for data visualization)
• cartodb-dark - Dark theme for night mode or high-contrast
• stamen-terrain - Terrain features visible
• stamen-toner - High contrast, black and white
• esri-satellite - Satellite imagery

Usage

Basic Map Creation

# Create a map from JSON data
opencode run "create a leaflet map from properties.json using latitude and longitude fields"

# Create a map from CSV data
opencode run "create a map from listings.csv with lat and lng columns"

Data Requirements

Your data must include location coordinates. The plugin will auto-detect common field names:

JSON Format:

[
  {
    "name": "Property 1",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "price": 850000,
    "type": "house"
  }
]

CSV Format:

name,latitude,longitude,price,type
Property 1,37.7749,-122.4194,850000,house
Property 2,37.7849,-122.4294,650000,condo

Supported Coordinate Field Names:

• Latitude: latitude, lat, y, Latitude, LAT
• Longitude: longitude, lng, lon, long, x, Longitude, LNG, LON

Styling Options

Color markers based on any property:

# Color by category
opencode run "create a map from data.json, color markers by property_type"

# Color by numeric value (creates gradient)
opencode run "create a map from data.json, color markers by price using red-yellow-green palette"

Available Color Palettes:

• default - Blue, green, red, purple, orange, pink, cyan, yellow
• rainbow - Full spectrum colors
• heat - Red to yellow gradient
• cool - Blue to green gradient
• grayscale - Black to white gradient

Filtering Data

# Filter by numeric range
opencode run "create a map from properties.json, only show properties with price between 500000 and 1000000"

# Filter by text value
opencode run "create a map from data.json, only show items where city equals 'Athens'"

# Combine filters
opencode run "create a map from listings.json, filter by price > 100000 and bedrooms >= 3"

Searching

# Search within the data
opencode run "search the properties map for entries containing 'downtown'"

# Search in specific fields
opencode run "search properties.json for items where neighborhood contains 'central'"

Heatmaps

# Create a basic heatmap
opencode run "create a heatmap from data.json showing density of points"

# Weighted heatmap
opencode run "create a heatmap from properties.json weighted by price"

Advanced Options

# Custom map center and zoom
opencode run "create a map from data.json centered at 37.98, 23.73 with zoom level 12"

# Use different tile provider
opencode run "create a map from data.json using cartodb-dark tiles"

# Custom popup fields
opencode run "create a map from properties.json showing name, price, and area in popups"

# Clustering disabled
opencode run "create a map from data.json without clustering"

Tools Reference

leaflet-test-connection

Test plugin configuration and status.

leaflet-create-map

Create an interactive Leaflet map from JSON or CSV data.

Parameters:

• filePath (required): Path to the data file
• latField: Latitude field name (auto-detected if not specified)
• lngField: Longitude field name (auto-detected if not specified)
• titleField: Field to use as marker title
• popupFields: Comma-separated list of fields to show in popups
• colorByField: Field to use for marker coloring
• colorPalette: Color palette name
• enableClustering: Enable marker clustering (default: true)
• clusterRadius: Clustering radius in pixels (default: 80)
• tileProvider: Map tile provider
• centerLat: Initial map center latitude
• centerLng: Initial map center longitude
• initialZoom: Initial zoom level (1-18)
• outputPath: Path for the generated HTML file

leaflet-filter-map

Filter map data by property values.

Parameters:

• filePath (required): Path to the data file
• filterField (required): Field to filter on
• filterOperator: Comparison operator (equals, contains, gt, lt, gte, lte, between)
• filterValue (required): Value to filter by
• filterValueEnd: End value for range filters
• Additional map creation parameters...

leaflet-search-data

Search within map data.

Parameters:

• filePath (required): Path to the data file
• searchQuery (required): Search term
• searchFields: Comma-separated list of fields to search
• searchType: Search type (contains, exact, startsWith, endsWith)
• Additional map creation parameters...

leaflet-create-heatmap

Create a heatmap visualization.

Parameters:

• filePath (required): Path to the data file
• weightField: Field for heatmap intensity weighting
• heatmapRadius: Radius of each heat point (default: 25)
• heatmapBlur: Blur amount (default: 15)
• maxIntensity: Maximum intensity value
• Additional map creation parameters...

leaflet-list-tiles

List available map tile providers.

leaflet-get-stats

Get statistics about your map data.

Parameters:

• filePath (required): Path to the data file
• statsField: Specific field for detailed statistics

Example Queries

# Real estate visualization
opencode run "create a map of all properties from properties.json colored by price"

# Store locations
opencode run "create a map from stores.csv showing name and address in popups"

# Event mapping
opencode run "create a heatmap of events from events.json weighted by attendance"

# Filtering results
opencode run "map only houses under $500k from listings.json"

# Analysis
opencode run "get statistics on the price field from properties.json"

Output

Generated HTML files are standalone and include:

• All necessary CSS and JavaScript inline
• No external dependencies required
• Works offline after generation
• Responsive design for all screen sizes
• Print-friendly styling

Default output location: ./leaflet-output/

Performance Tips

1. Enable Clustering: For datasets over 100 points, clustering significantly improves performance
2. Filter First: Apply filters to reduce data before creating maps
3. Limit Popup Fields: Only include essential fields in popups
4. Use Heatmaps: For very large datasets (10,000+), consider heatmaps instead of markers

Troubleshooting

Map is Empty

• Verify your data has valid latitude/longitude values
• Check field names match (use leaflet-get-stats to inspect data)
• Ensure coordinates are numbers, not strings

Markers Not Showing

• Check the browser console for JavaScript errors
• Verify data file path is correct and accessible
• Ensure data is valid JSON or CSV format

Performance Issues

• Enable clustering for large datasets
• Reduce the number of popup fields
• Consider using heatmap for very large datasets

License

MIT License

Contributing

Issues and pull requests welcome at OpenPets GitHub