UTFGrid provides a standard, scalable way of encoding data for hundreds or thousands of features alongside your map tiles.

The UTFGrid encoding scheme encodes interactivity data for a tile in a space efficient manner. It is designed to be used in browsers for interactive features like displaying tooltips when hovering over certain features of a map tile.

JSON format

UTFGrid uses a JSON object as a container format with the following keys:

• grid: The encoded grid of UTF-8 characters.
• keys: An array of ids identifying each character with a feature.
• data: A hash of data containing properties for each feature.

The grid

UTFGrids often look like map tiles translated into ASCII art (or UTF-8 art, that is). Each UTF-8 character represents a distinct feature on a map tile, like a unique country, road, lake or river. And since there are over a million UTF-8 code points each UTFGrid can represent extremely dense, varied data extremely efficiently.

          !######$$$$%%% %%%% % 
          !#######$$$$%%%    %%%
         !!#####   $$$%%%    %%%
         !######  $$$$%%% %% %%%
        !!!####  $$$$$%%%%  %%%%
      ! !###### $$$$$$%%%%%%%%%%
     ! !!#####  $$$$$$$%%%%%%%%%
    !!!!!####   $$$$$$%%%%%%%%%%
    !!!!!####   $$$$$$%%%%%%%%%%
    !!!!!####   $$$$$%%%%%%%%%%%
    !!!!!#####% $$   %%%%%%%%%%%
    !!!!!### #      %%%%%%%%%%%%
    !!! #####   ''''%%%%%%%%%%%%
     !   ###      ('%%%%%%%%%%%%
       ) ### #  ( ((%%%%%%%%%%%%
      ))  ##   (((((%%%%%%%%%%%%
      ))  #    ****(+%%%%%%%%%%%
       )        %**++++%%%%%%%%%
       , , ------*+++++%%%%%%%%%
.     ,,,,,------+++++++%%%%%%%%
..  /,,,,,,------++++++%%%%%%%%%
.  //,,,,,,------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

Once the UTFGrid has been received each character can be translated to its feature according to the keys and data properties. In this example,

• ! is mapped to Norway
• # is mapped to Sweden
• $ is mapped to Finland

And so on.

Feature data

Any given feature can contain as many fields as needed as a JSON object. For example, for Sweden the data hash may be an object storing Sweden’s ISO2 code, GDP, population and a link to its Wikipedia page:

{
    "iso2": "se",
    "gdp": 337893000000,
    "pop": 9400000,
    "wikipedia": "http://en.wikipedia.org/wiki/Sweden"
}