datamaps

Interactive maps for data visualizations. Bundled into a single Javascript file.

For feature requests, open an issue!

Contribution Guideliness

Demos at http://datamaps.github.io

Documentation

Getting Started

1. Include D3.js and Topojson on your page
2. Include Datamaps.js on your page
3. Add a container, set the height and width and position to relative
4. Create a new Datamaps(options), passing in at least an element option

<script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.5.3/d3.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/topojson/1.6.9/topojson.min.js"></script>
<script src="/datamaps.world.min.js"></script>
<div id="container" style="position: relative; width: 500px; height: 300px;"></div>
<script>
    var map = new Datamap({element: document.getElementById('container')});
</script>

via NPM

1. npm install datamaps
2. Refer to file in dist directory, like:

<script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.5.3/d3.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/topojson/1.6.9/topojson.min.js"></script>
<script src="node_modules/datamaps/dist/datamaps.world.min.js"></script>
<div id="container" style="position: relative; width: 500px; height: 300px;"></div>
<script>
    var map = new Datamap({element: document.getElementById('container')});
</script>

via Bower

1. bower install datamaps
2. Refer to file in dist directory, like:

<script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.5.3/d3.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/topojson/1.6.9/topojson.min.js"></script>
<script src="bower_components/datamaps/dist/datamaps.world.min.js"></script>
<div id="container" style="position: relative; width: 500px; height: 300px;"></div>
<script>
    var map = new Datamap({element: document.getElementById('container')});
</script>

USA Only Map

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        scope: 'usa'
    });
</script>

Changing the default fill colors

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        fills: {
            defaultFill: 'rgba(23,48,210,0.9)' // Any hex, color name or rgb/rgba value
        }
    });
</script>

Disabling popup or hover effects

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        geographyConfig: {
            highlightOnHover: false,
            popupOnHover: false
        }
    });
</script>

Using custom maps

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        geographyConfig: {
            dataUrl: '/custom.json'
        },
        scope: 'custom',
        setProjection: function(element, options) {
            var projection, path;
            projection = d3.geo.albersUsa()
                .center([long, lat])
                .scale(element.offsetWidth)
                .translate([element.offsetWidth / 2, element.offsetHeight / 2]);
}
            path = d3.geo.path()
                .projection( projection );

            return {path: path, projection: projection};
        }
    });
</script>

You can create any country's map using custom maps.

1. Find the {xyz}.topo.json file for you country xyz. You can find from https://github.com/markmarkoh/datamaps/tree/master/dist.
2. Extract Datamap.prototype.{xyz}Topo json and save it file named {xyz}.topo.json
3. If the state codes contains dot(.) in the topo json, then you need to remove the dot from the code e.g, if your state code is CA.AL, remove CA. part to get 2-digit ISO code AL. If the states code are already in 2-digit ISO or do't have dot(.) then don't do any modification follow next steps.
4. Objects country name in {xyz}.topo.json should be same as you declared in the Datamap scope. e.g, for Canada, in canada.topo.json we have {"type":"Topology","objects":{"can":{"type":"GeometryCollection"}}} and we have provided scope as 'canada' in the canada.html page. So this case 'can' in canada.topo.json must be as 'canada' i.e {"type":"Topology","objects":{"canada":{"type":"GeometryCollection"}}}.
5. You need to override setProjection method, which is explained above three countires. You can refer any one.
6. Done

1. Bubble map on India Geographical region

var bubble_map = new Datamap({
           element: document.getElementById('india'),
           scope: 'india',
           geographyConfig: {
               popupOnHover: true,
               highlightOnHover: true,
               borderColor: '#444',
               borderWidth: 0.5,
               dataUrl: 'https://rawgit.com/Anujarya300/bubble_maps/master/data/geography-data/india.topo.json'
               //dataJson: topoJsonData
           },
           fills: {
               'MAJOR': '#306596',
               'MEDIUM': '#0fa0fa',
               'MINOR': '#bada55',
               defaultFill: '#dddddd'
           },
           data: {
               'JH': { fillKey: 'MINOR' },
               'MH': { fillKey: 'MINOR' }
           },
           setProjection: function (element) {
               var projection = d3.geo.mercator()
                   .center([78.9629, 23.5937]) // always in [East Latitude, North Longitude]
                   .scale(1000);
               var path = d3.geo.path().projection(projection);
               return { path: path, projection: projection };
           }
});

Set the correct projection for India map on world map with the help of Longitude and Latitute of India (you can google it India Longitude and Latitute)

1. Bubble map on Canada Geographical region

var bubble_map = new Datamap({
            element: document.getElementById('canada'),
            scope: 'canada',
            geographyConfig: {
                popupOnHover: true,
                highlightOnHover: true,
                borderColor: '#444',
                borderWidth: 0.5,
                dataUrl: 'https://rawgit.com/Anujarya300/bubble_maps/master/data/geography-data/canada.topo.json'
                //dataJson: topoJsonData
            },
            fills: {
                'MAJOR': '#306596',
                'MEDIUM': '#0fa0fa',
                'MINOR': '#bada55',
                defaultFill: '#dddddd'
            },
            data: {
                'JH': { fillKey: 'MINOR' },
                'MH': { fillKey: 'MINOR' }
            },
            setProjection: function (element) {
                  var projection = d3.geo.mercator()
                .center([-106.3468, 68.1304]) // always in [East Latitude, North Longitude]
                .scale(250)
                .translate([element.offsetWidth / 2, element.offsetHeight / 2]);

                var path = d3.geo.path().projection(projection);
                return { path: path, projection: projection };
            }
        });

Set the correct projection for Canada map on world map with the help of Longitude and Latitute of Canada (you can google it Canada Longitude and Latitute)

if your map is not showing full view of East then you can change 32.1304 E to 70.3200 E or 30.3200 etc.*

Creating a Choropleth

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        fills: {
            HIGH: '#afafaf',
            LOW: '#123456',
            MEDIUM: 'blue',
            UNKNOWN: 'rgb(0,0,0)',
            defaultFill: 'green'
        },
        data: {
            IRL: {
                fillKey: 'LOW',
                numberOfThings: 2002
            },
            USA: {
                fillKey: 'MEDIUM',
                numberOfThings: 10381
            }
        }
    });

    // Draw a legend for this map
    map.legend();
</script>

Updating a choropleth after initial drawing

map.updateChoropleth({
   USA: {fillKey: 'LOW'},
   CAN: '#0fa0fa'
});

Resetting a choropleth to defaultFill

map.updateChoropleth({CA: 'green'}, {reset: true})

map.updateChoropleth(null, {reset: true})

map.updateChoropleth({NY: {numberOfVoters: 55452}}, {reset: true})

Choropleth with auto-calculated color

Custom popup on hover

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        fills: {
            HIGH: '#afafaf',
            LOW: '#123456',
            MEDIUM: 'blue',
            UNKNOWN: 'rgb(0,0,0)',
            defaultFill: 'green'
        },
        data: {
            IRL: {
                fillKey: 'LOW',
                numberOfThings: 2002
            },
            USA: {
                fillKey: 'MEDIUM',
                numberOfThings: 10381
            }
        },
        geographyConfig: {
            popupTemplate: function(geo, data) {
                return ['<div class="hoverinfo"><strong>',
                        'Number of things in ' + geo.properties.name,
                        ': ' + data.numberOfThings,
                        '</strong></div>'].join('');
            }
        }
    });
</script>

Bubbles

var bombMap = new Datamap({
    element: document.getElementById('map_bombs'),
    scope: 'world',
    geographyConfig: {
        popupOnHover: false,
        highlightOnHover: false
    },
    fills: {
        'USA': '#1f77b4',
        'RUS': '#9467bd',
        'PRK': '#ff7f0e',
        'PRC': '#2ca02c',
        'IND': '#e377c2',
        'GBR': '#8c564b',
        'FRA': '#d62728',
        'PAK': '#7f7f7f',
        defaultFill: '#EDDC4E'
    },
    data: {
        'RUS': {fillKey: 'RUS'},
        'PRK': {fillKey: 'PRK'},
        'PRC': {fillKey: 'PRC'},
        'IND': {fillKey: 'IND'},
        'GBR': {fillKey: 'GBR'},
        'FRA': {fillKey: 'FRA'},
        'PAK': {fillKey: 'PAK'},
        'USA': {fillKey: 'USA'}
    }
});

     var bombs = [{
        name: 'Joe 4',
        radius: 25,
        yield: 400,
        country: 'USSR',
        fillKey: 'RUS',
        significance: 'First fusion weapon test by the USSR (not "staged")',
        date: '1953-08-12',
        latitude: 50.07,
        longitude: 78.43
      },{
        name: 'RDS-37',
        radius: 40,
        yield: 1600,
        country: 'USSR',
        fillKey: 'RUS',
        significance: 'First "staged" thermonuclear weapon test by the USSR (deployable)',
        date: '1955-11-22',
        latitude: 50.07,
        longitude: 78.43

      },{
        name: 'Tsar Bomba',
        radius: 75,
        yield: 50000,
        country: 'USSR',
        fillKey: 'RUS',
        significance: 'Largest thermonuclear weapon ever tested—scaled down from its initial 100 Mt design by 50%',
        date: '1961-10-31',
        latitude: 73.482,
        longitude: 54.5854
      }
    ];
//draw bubbles for bombs
bombMap.bubbles(bombs, {
    popupTemplate: function (geo, data) {
            return ['<div class="hoverinfo">' +  data.name,
            '<br/>Payload: ' +  data.yield + ' kilotons',
            '<br/>Country: ' +  data.country + '',
            '<br/>Date: ' +  data.date + '',
            '</div>'].join('');
    }
});

Live updating of bubbles

Labels

map.labels();

map.labels({labelColor: 'blue', fontSize: 12});

newLabels = {'AK':'Alaska', 'AL':'123',.......};
map.labels({'customLabelText': newLabels});

Zooming

var map = new Datamap({
  scope: 'world',
  element: document.getElementById('container1'),
  setProjection: function(element) {
    var projection = d3.geo.equirectangular()
      .center([19, -3])
      .rotate([4.4, 0])
      .scale(400)
      .translate([element.offsetWidth / 2, element.offsetHeight / 2]);
    var path = d3.geo.path()
      .projection(projection);

    return {path: path, projection: projection};
  },

Using with jQuery

<script>
    $("#container").datamaps(options);
</script>

Events

<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        done: function(datamap) {
            datamap.svg.selectAll('.datamaps-subunit').on('click', function(geography) {
                alert(geography.properties.name);
            });
        }
    });
</script>

Responsive Maps

<div id="container"></div>
<script>
    var map = new Datamap({
        element: document.getElementById('container'),
        responsive: true
    });

    // Pure JavaScript
    window.addEventListener('resize', function() {
        map.resize();
    });

    // Alternatively with d3
    d3.select(window).on('resize', function() {
        map.resize();
    });

    // Alternatively with jQuery
    $(window).on('resize', function() {
       map.resize();
    });
</script>

Default Options

{
  scope: 'world', // Currently supports 'usa' and 'world', however with custom map data you can specify your own
  setProjection: setProjection, // Returns a d3 path and projection functions
  projection: 'equirectangular', // Style of projection to be used. try "mercator"
  height: null, // If not null, datamaps will grab the height of 'element'
  width: null, // If not null, datamaps will grab the width of 'element',
  responsive: false, // If true, call `resize()` on the map object when it should adjust it's size
  done: function() {}, // Callback when the map is done drawing
  fills: {
    defaultFill: '#ABDDA4' // The keys in this object map to the "fillKey" of [data] or [bubbles]
  },
  dataType: 'json', // For use with dataUrl, currently 'json' or 'csv'. CSV should have an `id` column
  dataUrl: null, // If not null, datamaps will attempt to fetch this based on dataType ( default: json )
  geographyConfig: {
      dataUrl: null, // If not null, datamaps will fetch the map JSON (currently only supports topojson)
      hideAntarctica: true,
      hideHawaiiAndAlaska : false,
      borderWidth: 1,
      borderOpacity: 1,
      borderColor: '#FDFDFD',
      popupTemplate: function(geography, data) { // This function should just return a string
        return '<div class="hoverinfo"><strong>' + geography.properties.name + '</strong></div>';
      },
      popupOnHover: true, // True to show the popup while hovering
      highlightOnHover: true,
      highlightFillColor: '#FC8D59',
      highlightBorderColor: 'rgba(250, 15, 160, 0.2)',
      highlightBorderWidth: 2,
      highlightBorderOpacity: 1
  },
  bubblesConfig: {
      borderWidth: 2,
      borderOpacity: 1,
      borderColor: '#FFFFFF',
      popupOnHover: true, // True to show the popup while hovering
      radius: null,
      popupTemplate: function(geography, data) { // This function should just return a string
        return '<div class="hoverinfo"><strong>' + data.name + '</strong></div>';
      },
      fillOpacity: 0.75,
      animate: true,
      highlightOnHover: true,
      highlightFillColor: '#FC8D59',
      highlightBorderColor: 'rgba(250, 15, 160, 0.2)',
      highlightBorderWidth: 2,
      highlightBorderOpacity: 1,
      highlightFillOpacity: 0.85,
      exitDelay: 100, // Milliseconds
      key: JSON.stringify
  },
  arcConfig: {
    strokeColor: '#DD1C77',
    strokeWidth: 1,
    arcSharpness: 1,
    animationSpeed: 600, // Milliseconds
    popupOnHover: false, // True to show the popup while hovering
    popupTemplate: function(geography, data) { // This function should just return a string
      // Case with latitude and longitude
      if ( ( data.origin && data.destination ) && data.origin.latitude && data.origin.longitude && data.destination.latitude && data.destination.longitude ) {
        return '<div class="hoverinfo"><strong>Arc</strong><br>Origin: ' + JSON.stringify(data.origin) + '<br>Destination: ' + JSON.stringify(data.destination) + '</div>';
      }
      // Case with only country name
      else if ( data.origin && data.destination ) {
        return '<div class="hoverinfo"><strong>Arc</strong><br>' + data.origin + ' -> ' + data.destination + '</div>';
      }
      // Missing information
      else {
        return '';
      }
    }
  }
}

• Do not run the grunt build task or submit any built files in your PR.
• Have an example in src/examples if adding a new feature. Copy an existing feature .html file to start.