Design Studio SDK: How to create home-made map files for Choropleth Maps

Audience:

This is for developers who want to get their hands a little dirty for the reward of some mapping flexibility and independence.

Context:

This is primarly for my Open Source Choropleth mapping component (Link here: Design Studio SDK (1.3/1.4) – Open Source Maps (Part 2) Choropleth Maps).  Similar to my Part 1 blog on Maps, they have a lot of information.  For my next step, I wanted to leave the flexibility and knowledge of how to develop your own map geometries in your hands.  I still think Maps are hard, but no longer in all capital letters.  🙂   My Chroropleth maps will provide some general-purpose maps, such as World-level Country features, and some example Country-level Regional features for US and Germany.  Since I am a one-man shop doing this for fun and free, I’m not in the business of converting all maps and all levels of geographic granularity.  But let’s see what’s involved with making our own!

Scenario:

I have a data set for China at a province/regional level which is not provided out of the box in the Open Source Choropleth Map Component.  I want to create the necessary file that can be used by this component though.

Workflow:

We will need to download the .SHP and .DBF files for China.  A great free resource can be found here: Download data by country | DIVA-GIS

And the contents of the .ZIP:

I found a great site that will let you view the .shp files quickly.  mapshaper

The next screen you will see the geometry in the .shp file to be sure this is what you want.

This looks like what I am after, however if I had a specific need for even more regional granularity, it is available, here’s an example, just for reference:

So now that we’ve identified our .shp file (CHN_adm1.shp), there is a corresponding .dbf (CHN_adm1.dbf) file by the same title.

Next we need to convert this data into TopoJSON (or GeoJSON) format for use in the map component.  There’s more than one to do this.  We cannot use the MapShaper website because it only converts the shapes (.shp) – We lose the attributes (like name of each feature) which are contained in the .DBF file.  There is a QGIS application (Download QGIS) that can export this to GeoJSON however it’s pretty daunting to use.  It’s a valid approach but it’s a big download and I just want something to do in the command line.

So what I did was used the node package by the same MapShaper guys.  Prerequisite is that you’ve installed Node on your workstation (it’s not hard.)

1) Install MapShaper node package (Instructions here: https://github.com/mbloch/mapshaper)

2) Next, I referred to the command-line instructions here: Command Reference · mbloch/mapshaper Wiki · GitHub

3) I came up with this command that has the magic amount of parameters to produce a good (and compressed) TopoJSON format file.  (Modify your paths as needed):

mapshaper -i shp\CHN_adm1.shp encoding=utf8 -simplify 5% -o China-regions.json format=topojson

This also takes a 14MB shp+dbf file and compresses the geometry down by 30% to the topojson file called China-regions.json weighing in at 385KB!  You can play with the -simplify parameter to even make it smaller at the tradeoff of less detail as you go.  Hint: You can use the mapshaper website to play with the simplify slider (shown in prior screenshots) in realtime to find an acceptable simplification ratio to save you some time!

Since this is a custom map, now it is up to you where to host it.  If you are in a corporate environment perhaps on a local intranet site, or perhaps you can post it externally or maybe we can all find a nice repository of them to host on and collaborate!

So let’s prove this works in the upcoming Open Source Choropleth Maps component!

Looks like China to me!  I made a quick datasource with a handful of the provinces you see shaded above and the end result is our very own home made Choropleth Map in Design Studio.

Again, there will be a more in-depth blog to come related to the component itself, but I hope this blog gets some of us geeks excited at the prospect of map independence.  Another example shot below with some of the canned maps that will come out of box however:

Link to the Design Studio Component: Design Studio SDK (1.3/1.4) – Open Source Maps (Part 2) Choropleth Maps

Summary of Resources Used:

• QGIS: Download QGIS
• Free country administrative data: Download data by country | DIVA-GIS
• This blog entry thematic mapping blog: Converting shapefiles to TopoJSON + a GitHub secret
• Natural Earth resources: Downloads | Natural Earth
• mapshaper
• Node.js