adamwgriffin/googlemapspointclusterd3

Google Maps Pin Clustering with Spiderification using D3.JS

Google Maps Clustering Using D3.JS

A simple to use, very fast, point clustering library for Google maps. Uses other amazing open source projects to accomplish goal. Credits below.

Demo

Clusering Demo Here

First, a thank you to the open source libraries used in this project.

1. D3JS - Without it the complex quadtree math would have been impossible for my tiny brain.
2. Google Maps Overlapping Marker Spiderfier used to spider overlapping markers.

Also, a special thank you to these D3 projects and articles that allowed me to figure out how to accomplish this task:

1. https://www.phase2technology.com wrote a great blog post about utilizing D3 to accomplish complex clustering.
2. https://thoughbot.com wrote possibly the best article I had come across on how to accomplish this with ObjectiveC example code.
3. http://bl.ocks.org/mbostock/4343214 one of many great D3 examples out in the internet.

Why?

IMO, the current Google Maps Cluster library (See library here) is really inefficient when dealing with massive amounts of points as it creates a Google Maps Marker object for each point before clustering them.

Install

Using NPM:

npm i google-maps-d3-marker-cluster --save-dev

In App

import 'google-maps-d3-marker-cluster'

The import sets the constructor, PointCluster, object for you. See below for implementation.

Basic Implementation

Required Libraries

<script src="//maps.google.com/maps/api/js?key={YOUR_KEY}"></script>
<script src="//d3js.org/d3.v4.min.js"></script>
<script src="//d3js.org/d3-quadtree.v1.min.js"></script>

Expected data structure

// example.json
{
  "data": {
    "result_list": [
      {
        "lat": 39.498234,
        "lng": -121.54583,
        ... more
      },
      ... more...
    ]
  }
}

Create a Point Cluster Instance

var pc = new PointCluster({
    map: map, // Pass in your Google map intance.
    clusterRange: 300, // clusterRange is the pixel grid to cluster. Smaller = more clusters / Larger = less clusters.
    threshold: 300, // Threshold is the number of results before showing markers,
    clusterRgba: '255, 0, 102, .8', // Change the background of the cluster icon. RGBA only.
    clusterBorder: '5px solid #dcdcdc', // Change the border around the icon. HEX only.
    polygonStrokeColor: '#0f0f0e', // Polygon stroke color.
    polygonStrokeOpacity: '0.5', // Polygon stroke opacity.
    polygonStrokeWeight: '4', // Polygon stroke weight.
    polygonFillColor: '#0f0f0e', // Polygom fill color.
    polygonFillOpacity: '0.2', // Polygon fill color.
    customPinHoverBehavior: false, // If the user of the lib would rather not use internal overlay and opt for their own hover behavior.
    customPinClickBehavior: false // If the user of the lib would rather not use internal overlay and opt for their own click behavior.
});

Get your data and set your point collection on the instance

// Get example.json
d3.json('example.json', function(error, res) {
  // In this example, we're mutating the results to add data attributes, hover data, and click data. This can obviously be done without mutation... 
  res.data.result_list.forEach(function(o, i) {
    o.hoverData = o.lat + " : " + o.lng;
    o.dataset = [{foo: 'bar'}] // Dataset is an array of objects. This would add: data-foo="bar" to marker points.
    o.clickData = "You've clicked on this locaton:<br />" + o.lat + " : " + o.lng; // Data to present on click of a marker point
  });
  // Set the collection of location objects.
  pc.setCollection(res.data.result_list);

  // Print clusters
  pc.print();
})

Development and Building

Dev

I am assuming you have node (v8+) installed, webpack installed (v3+), and webpack-dev-server (v2+) installed globally.

Fork the repository and clone it locally. Navigate into your cloned directory and run:

npm run dev

This will fire up the dev server on http://localhot:8080

Main development files are in the src directory. Changes automatically update the dist/bundle.js for development.

Build

Run the following:

npm run build

This creates a versioned and minified file in the build directory.

Coming soon

1. Better examples on how to utilize this library.
2. Tricks for styling markers.
3. Utilizing the internal Publish/Subscribe API to do custom popovers/hover effects on click/touch and mouseenter.