Scalable interaction

Some of the most compelling stories that can be told with maps require thousands of interactive points or polygons: mapping over 17,000 poisoned places in America, visualizing the distribution of Asian Americans by county, or showing the impact of poverty on American communities. Downloading and displaying thousands of interactive features can be challenging even for modern devices on fast connections. The UTFGrid spec defines a way to tile interaction data so that it loads progressively and performs well across legacy browsers and modern mobile devices.

View the spec utfgrid-spec is an open specification on GitHub. Fork the repository and create issues or pull requests to improve the next version.

Map data as ASCII art

Older computers and browsers pose a particular challenge to map interaction: drawing large amounts of vector data is slow or sometimes not supported at all. UTFGrid’s solution to this problem is to rasterize polygons and points in JSON as a grid of text characters. Each feature is referenced by a distinct character and associated to JSON data by its character code. The result is a cheap, fast lookup that even Internet Explorer 7 can do instantly.

UTFGrid tile data often looks like an ASCII art version of the corresponding map and is where the spec gets its name:

          !######$$$$%%% %%%% % 
          !#######$$$$%%%    %%%
         !!#####   $$$%%%    %%%
         !######  $$$$%%% %% %%%
        !!!####  $$$$$%%%%  %%%%
      ! !###### $$$$$$%%%%%%%%%%
     ! !!#####  $$$$$$$%%%%%%%%%
    !!!!!####   $$$$$$%%%%%%%%%%
    !!!!!####   $$$$$$%%%%%%%%%%
    !!!!!####   $$$$$%%%%%%%%%%%
    !!!!!#####% $$   %%%%%%%%%%%
    !!!!!### #      %%%%%%%%%%%%
    !!! #####   ''''%%%%%%%%%%%%
     !   ###      ('%%%%%%%%%%%%
       ) ### #  ( ((%%%%%%%%%%%%
      ))  ##   (((((%%%%%%%%%%%%
      ))  #    ****(+%%%%%%%%%%%
       )        %**++++%%%%%%%%%
       , , ------*+++++%%%%%%%%%
.     ,,,,,------+++++++%%%%%%%%
..  /,,,,,,------++++++%%%%%%%%%
.  //,,,,,,------000++000%%%%%%%
  211,,,,,33------00000000%%%%%%
 2221,,,,33333---00000000000%%%%
222222,,,,3635550000000000000%%%
222222,,,,6665777008900000000%%%
22222::66666777788889900000 %%%%
22222:;;;;%%=7%8888890  0   %%%%
22222;;;; ==??%%888888  00 %%%%%
222222 ;;  =??%%%8888       %%%%
222     ;;   ?A>>@@@          B%
CCC      ;;   DEE@@@          BB

How it works

UTFGrid interaction is handled seamless by mapbox.js and the Mapbox iOS SDK. Under the hood, the process follows a simple tile retrieval and feature lookup workflow.

  1. When user interaction occurs (a hover, click or tap on a map tile) a corresponding UTFGrid tile is downloaded.
  2. The x,y coordinates of the user interaction correspond to a character in the UTFGrid. In the grid above, a tap at column 13, row 4 would look up the # character.
  3. Each UTFGrid character corresponds to a distinct feature retrieved using a key mapping. In the grid above the characters are mapped such that

      ! => Norway
      # => Sweden
      $ => Finland
    
  4. The feature JSON data is passed to a mustache template for display as HTML. Once rendered the data above is seen as an interactive map tooltip.

    Sweden
    Population 9400000
    Learn more on Wikipedia

UTFGrid in action

Any custom maps you make in TileMill with interaction make use of UTFGrid tiles in MBTiles exports. You can enable UTFGrid interaction on your maps using the L.mapbox.gridLayer() call in Mapbox.js.

Mission complete! Next up:

  • We’ve looked at how UTFGrid makes fast interaction possible for thousands of point and polygon features. In the next section we’ll get into concrete examples that use Mapbox web services.