Build Status | Coverage Status



  • Configurable heatmaps of result sets
    • Works with center points and bounding box data
  • Show page map view
  • Changeout the basemap to any tile layer
  • Really fast with large data sets
    • Utilizes Solr's facet heatmap feature to provide snappy results. Tested with an index > 10,000,000 records.
  • Customizable result view template


Add this line to your application's Gemfile:

gem 'blacklight_heatmaps'

And then execute:

bundle install

Run the BlacklightMaps installer:

rails generate blacklight_heatmaps:install

Getting started

Indexing data

BlacklightHeatmaps expects your data to be indexed as a Spatial Recursive Prefix Tree type. The plugin currently supports data indexed in formats:

  • x y Syntax. example: "-121.631609 36.688128"
  • CQL ENVELOPE Syntax (minX, maxX, maxY, minY). example: "ENVELOPE(122.934585571, 153.987060547, 45.522888184, 20.422889709)"

BlacklightHeatmaps also works with multivalued Spatial Recursive Prefix Tree types.

  "id": 1,
  "name": "Null Island",
  "geo_srpt": [
    "ENVELOPE(-0.0005, 0.000379, 0.000309, -0.000282)", "0 0"

Solr does not seem to be able to handle multivalued points without an accompanying geometry.

Additional formats could be added by extending BlacklightHeatmaps::GeometryParser

Customizing the basemap

By default three different basemaps are included with BlacklightHeatmaps. You can modify these by changing the configuration value in the CatalogController.

  # Basemaps configured include: 'positron', 'darkMatter', 'OpenStreetMap.HOT'
  config.basemap_provider = 'OpenStreetMap.HOT'

BlacklightHeatmaps allows you to customize your basemap further to any Leaflet TileLayer subclass. This includes WMS layers, TileLayers, etc. Checkout Leaflet Providers for more ideas on basemaps you can use.

To customize the basemap, make sure that you extend the BlacklightHeatmaps.Basemaps object to include your basemap selection:

  BlacklightHeatmaps.Basemaps[' OpenStreetMap.BlackAndWhite'] = L.tileLayer('http://{s}{z}/{x}/{y}.png', {
    maxZoom: 18,
    attribution: '&copy; <a href="">OpenStreetMap</a>'

Customizing the color display

The heatmap color ramp is also customizable. This setting can be modified in CatalogController by passing in an array of hexadecimal color values as strings.

  #Heatmap color ramp. For best results, use or
  config.view.heatmaps.color_ramp = ['#fef0d9','#fdcc8a','#fc8d59','#e34a33','#b30000']


ColorBrewer is a great resource in choosing a color ramp. It also has options for colorblind safe ramps to use and can export the hex values in an array that you can paste into your configuration.


Run Solr and Blacklight (with BlacklightMaps) for interactive development:

bundle exec rake blacklight_heatmaps:server

Run the test suite

bundle exec rake ci