Skip to content

Understanding the TopoJSON data format

19. March 2013

This extension of the, meanwhile standardised, GeoJSON dataformat encodes topology of a GeoJSON dataset and reduces file size up do 80% (see authors description).

In order to use this dataformat, it can be usefull to understand the structure of a TopoJSON file. That is why I will break it appart and analyse each element in the following. A more detailed description of the dataformat can be found here.

Let’s begin with the creation of a TopoJSON file.

In an earlier post, I have concluded how to make a map of germany from such a file by using D3.js. So in conclusion, you take one or more GeoJSON file(s) and convert it(them) to one compact TopoJSON file. This could look as follows:

topojson \
 --id-property postal \
 -p postal \
 -p name \
 -o de-data.json \
 states.json

What are the different parts responsible for?

  • “–id-property” –> specifies which attribute will be used as ID(entifier) … in this example it is the attribute ‘postal’
  • “-p” –> specifies which attributes will be preserved respectively transfered from source to the TopoJSON file … in this example it is the ‘postal’ & ‘name’ attribute
  • “-o” –> specifies the name of the output TopoJSON file
  • “nothing” –> there is(are) the input file(s) specified .. in this example only the german states

Now, let’s have a look at the resulting file (as abstract):

{
 "type":"Topology",
 "transform":{"scale":[0.0009170486546988356,0.0007794992965075303],
 "translate":[5.852489868512635,47.27112091110115]},
 "objects":{
   "states":{"type":"GeometryCollection",
    "geometries":[
     {"type":"Polygon","arcs":[[0,1,2,3]],"id":"NW","properties":{"name":"Nordrhein-Westfalen","postal":"NW"}},
     ...
     {"type":"Polygon","arcs":[[8,9,-6,10,-1,11]],"id":"HE","properties":{"name":"Hessen","postal":"HE"}},
     ...
     {"type":"MultiPolygon","arcs":[[[59]],[[60]],[[61]],[[-58,-26,-44,62]],[[63]],[[64]]],"id":"MV","properties":{"name":"Mecklenburg-Vorpommern","postal":"MV"}}
    ]
   }
  },
  "arcs":[
     [[3912,5616],[-17,-22],[-7,-6],[-79,-19],[-9,-4],[-5,-3],[1,-2],[4,-3],[2,-1],[14,-7],[2,-1],[1,-2],[0,-2],[0,-2],[0,-2],[-5,-8],[-2,-4],[-2,-5],[-3,-7],[0,-2],[-1,-2],[-3,-8],[-4,-10],[-5,-5],[-6,-5],[-11,-8],[-6,-5],[-4,-6],[-5,-10],[-3,-4],[-4,-3],[-14,-6],[-14,-10],[-8,-4],[-12,-3],[-21,-10],[-5,-3],[-4,-4],[-3,-4],[-2,-4],[-1,-5],[0,-2],[0,-3],[0,-4],[0,-1],[-1,-3],[-1,-4],[-3,-6],[-2,-2],[-3,-1],[-12,2],[-6,-2],[-39,-22],[-4,-1],[-9,0],[-40,6],[-21,13],[-5,5],[-1,2],[0,2],[1,13],[1,1],[1,3],[-3,12],[-6,7],[-4,4],[-4,1],[-5,-1],[-3,0],[-16,6],[-21,12],[-10,3],[-6,2],[-17,-7],[-45,-8],[-57,-21],[-4,-4],[-2,-2],[-1,-4],[-2,-5],[0,-4],[1,-2],[1,-2],[10,-10],[1,-2],[3,-5],[2,-5],[2,-12],[0,-3],[0,-12],[0,-3],[1,-2],[1,-1],[2,-1],[23,-2],[3,-1],[3,-2],[3,-4],[0,-5],[-2,-5],[-6,-11],[-4,-4],[-4,-2],[-45,-2],[-11,-3],[-28,-16],[-2,0],[-3,-1],[-3,0],[-23,6],[-5,2],[-5,1],[-6,0],[-6,0],[-14,-1],[-26,-7],[-22,-2],[-19,1],[-8,-2],[-25,-8],[-21,-4],[-4,-2],[-2,-2],[0,-2],[-7,-9],[-12,-5],[-9,-5],[-1,-2],[0,-2],[-1,-1],[-1,-4],[-3,-3],[-36,-27],[-24,-23],[-6,-7],[-11,-18],[-2,-5],[-1,-3],[1,-1],[1,-2],[1,-2],[2,-1],[5,-4],[7,-3],[4,-3],[1,-2],[1,-1],[1,-5],[1,-5],[1,-1],[1,-2],[2,-2],[2,-1],[5,-2],[10,-1],[5,0],[3,1],[3,1],[3,3],[5,8],[1,1],[2,1],[3,1],[5,2],[22,1],[22,5],[24,13],[6,2],[4,1],[3,-1],[2,-1],[2,-2],[1,-1],[0,-2],[0,-2],[-4,-9],[0,-2],[0,-1],[2,-1],[8,-3],[2,-2],[1,-1],[5,-16],[1,-4],[1,-3],[6,-22],[1,-5],[4,-16],[1,-1],[0,-2],[2,-7],[1,-3],[0,-5],[0,-8],[-1,-4],[-1,-3],[-35,-29],[-22,-22],[-3,-3],[0,-2],[0,-1],[1,-2],[1,-2],[9,-11],[2,-4],[0,-6],[-1,-3],[-2,-2],[-28,-11],[-14,-9],[-3,-1],[-3,0],[-2,0],[-34,7],[-112,-1],[-5,-10],[4,-6],[5,-5],[7,-12],[3,-5],[1,-4],[-3,-5],[-1,-8],[2,-8],[6,-17],[2,-8],[1,-5],[-7,-9],[-12,-10],[-2,-2],[-3,-6],[-4,-8],[-5,-7],[-3,-6],[-1,-2],[-2,-2],[-2,-1],[-3,0],[-8,-2],[-7,-6],[-14,-23],[-9,-14],[-1,-3],[0,-7],[-1,-20],[-2,-5],[-3,-3],[-2,0],[-13,2],[-6,0],[-18,-9],[-29,-21],[-4,-5],[0,-6],[1,-6],[-2,-3],[-2,-3],[-22,-13],[-6,-2],[-5,-2],[-14,0],[-16,-2],[-18,2],[-6,4],[-9,16],[-4,3],[-4,2],[-13,-1],[-4,-1],[-3,-2],[-14,-12],[-47,-32],[-2,-2],[-5,-6],[-2,-2],[-21,-11],[-2,-2],[-1,-2],[-8,-16],[-52,-34],[-6,-5],[-1,-2],[0,-2],[0,-2],[0,-1],[2,-2],[2,-1],[2,-1],[2,-1],[2,-2],[0,-1],[-1,-4],[1,-2],[1,-1],[2,-2],[24,-14],[5,-4],[2,-2],[1,-2],[1,-2],[0,-2],[-6,-34],[-3,-10],[-3,-3],[-3,-2],[-12,-2],[-4,-3],[-3,-3],[-11,-18]],
     ...
     [[8238,8925],[-31,3],[-35,9],[-38,17],[8,7],[6,15],[12,20],[-16,-7],[-8,-5],[-6,-6],[4,-4],[3,-4],[-22,1],[-11,-1],[-8,-5],[-10,-4],[-11,5],[-10,8],[-7,4],[-16,2],[-19,6],[-12,11],[6,17],[-15,3],[-34,-11],[-11,-1],[-7,10],[6,8],[15,4],[17,-5],[0,8],[-68,36],[15,28],[21,22],[28,9],[33,-15],[8,9],[13,-9],[15,2],[32,15],[-17,2],[-13,8],[-5,13],[5,13],[0,8],[-15,1],[-8,6],[-7,7],[-11,4],[-49,-9],[19,27],[8,6],[30,6],[33,11],[22,3],[0,9],[1,0],[7,3],[7,6],[-30,8],[-14,6],[-8,11],[3,3],[4,2],[2,5],[-1,9],[-32,-9],[-20,-2],[-8,6],[-3,4],[-5,1],[-5,3],[-2,10],[-2,11],[-4,7],[-7,3],[-10,0],[25,8],[84,9],[18,-3],[6,-8],[13,-3],[12,-7],[6,-17],[5,-9],[8,5],[4,14],[-9,20],[16,15],[20,14],[20,11],[19,5],[-12,-26],[-8,-11],[-10,-8],[7,1],[6,-1],[5,-3],[5,-6],[-5,-6],[-11,-19],[16,-1],[13,4],[10,8],[6,14],[-9,2],[-10,5],[-10,2],[0,9],[15,10],[12,-17],[19,-17],[13,-18],[-7,-19],[22,-22],[27,-6],[56,1],[-8,9],[10,17],[6,6],[7,4],[0,9],[-9,18],[-6,9],[-8,7],[0,9],[6,3],[4,3],[4,2],[9,2],[0,8],[-14,-1],[-8,-5],[-7,-7],[-8,-5],[-12,-1],[-38,1],[-5,4],[-6,9],[-8,9],[-10,4],[-17,3],[-6,6],[-4,9],[-7,9],[-13,12],[-2,6],[-15,-9],[-9,-6],[-17,-17],[-26,-10],[-18,-14],[-20,-10],[-22,5],[-4,15],[8,24],[14,21],[16,10],[3,5],[5,12],[2,12],[-3,6],[-49,-9],[-16,-8],[-7,2],[1,15],[6,8],[11,9],[14,6],[149,30],[31,0],[28,-10],[0,-8],[-16,-9],[-23,-9],[-20,-12],[-8,-18],[3,-23],[9,-18],[15,-14],[18,-11],[46,-11],[141,19],[48,-7],[33,-25],[8,-33],[-29,-31],[-48,-23],[-24,-16],[-10,-18],[4,-22],[9,-22],[12,-19],[12,-12],[22,-8],[52,-8],[22,-12],[29,-36],[19,-17],[27,-7],[-15,-7],[-14,-13],[-11,-16],[-4,-21],[0,-21],[-3,-8],[-12,1],[-24,6],[13,0],[10,4],[5,9],[-5,13],[-7,0],[-11,-8],[-17,-5],[-18,0],[-13,5],[0,8],[41,12],[16,9],[9,15],[-56,-3],[-26,-5],[-21,-10],[60,29],[20,6],[0,9],[-29,1],[-15,-1],[-11,-5],[-14,-12],[-10,3],[-8,9],[-12,5],[-109,-9],[-20,-9],[-57,-35],[-12,-13],[-13,-20],[-27,-4],[-24,-8],[-4,-35],[15,9],[0,7],[-2,1],[-3,0],[-2,2],[52,6],[8,-2],[8,-30],[-3,-13],[-17,-6]]
  ]
}

The necessary parts are the information, that are included in the objects.

On the one hand it contains a condensed form of the original GeoJSON file(s)…here only one, the ‘states’ element. Therein are all geometries, described by ‘arcs’, ‘id’ and ‘properties’. Here you can find the initially specified attributes again…do you remember, we wanted to preserve ‘name’ & ‘postal’. And you see also, that the ‘id’ is equal with the ‘postal’ attribute, as we have initially specified. The ‘arcs’ – element is an GeoJSON geometry specified array of all arcs that have to be used to rebuild this geometry. In our example, you can see the ‘arcs’ element is exactly the same syntax as in the GeoJSON specification, for Polygon or MultiPolygon. The elements within that array are just a pointer to the appropriate arc in the arcs-list.

On the other hand it contains an array, containing all geometries (arcs) of the original geometries. To get the geometry of “Nordrhein-Westfalen”, we only have to get the corresponding 4 arcs ([0,1,2,3]) of the arcs-object.

TopoJSON is used to avoid redundancy by saving redundant geometries only once. You can see that in the example. “Hessen” shares one border with “Nordrhein-Westfalen”. Therefore it is not specified as an additional arc in the geometrical definition of “Hessen”. No, it is described by the same “arc-id” with a negative sign…this is ‘-1’ in the example. You can see “Hessen” seems to share also another border with another german state…-6…but this one is not listed in this abstracted example.

Advertisements
3 Comments
  1. draschke permalink

    Thanks, this is really very helpful!!!

Trackbacks & Pingbacks

  1. D3 Geodata Basics – A Map Overlay can have many Faces : digital-geography.com

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: