Data Map

Best Practices

Note:  The WCMS uses the same content builder for data maps and navigation-only maps, but given the different purposes of the two map types, the guidance is different.  The guidance on navigation-only maps is in the Navigation section of this Gallery.


A data map displays numeric or categorical data in a color-coded map. Users can filter data by clicking the legend categories and sort data using the column headings in the data table. By default, the data table can display in collapsed or expanded view, as set in the WCMS. Data maps can be inserted as regular content elements or as shareable widgets.

The illustration below is a static image.  To understand this guidance, it may help to interact with some live map examples before reading further.  See the “Go to Examples” module on the right for links to maps that illustrate a variety of map features.

Screen capture of data map with cities

Each data map is driven by a JSON or CSV source data file typically prepared by the content owner. For information on data file format, see the WCMS instructions.

New Features!

With WCMS 4.9.6, world data maps are supported.  You can download a sample CSV data file excel icon[XLS – 11 KB] for world maps. Note that the country names are used as identifiers and cannot change.

With WCMS 4.8.9, the 100 most populous U.S. cities excel icon[XLS – 1 KB] are supported for U.S. data maps. And cities are now plotted on the map.  The illustration above shows data for both cities and states/territories, but city-only maps are also supported.  See “Working with City Data” below for tips on working with cities in a data map. A an example map with cities is available.


Use a data map to display geographically color-coded numeric or categorical data, such as prevalence of a specific disease, case counts for an outbreak, or percentage of adults in a health program.  For states or countries with “special values” (such as “*” or “NA”), you can specify up to two special classes. The map tool automatically color-codes these special classes with two shades of gray, one for each special class.

Note that a data map can serve as a navigation aid if URLs are provided in the data file. (If there are no data for color-coding, use the navigation-only map.)

Data Classification

For data maps the WCMS offers three types of data classification:

  • Equal Number (Quantile) places the states into numeric data classes of the same size.
  • Equal Interval divides the numeric range into subranges of equal size (good for showing outliers). The example numeric maps show how the same data display in equal number vs. equal interval classification types.
  • Categorical is for non-numeric classification. See example categorical maps.

Data classification can affect a map user’s perception of the data story. To determine the best classification for a numeric map, web developers should work closely with content owners to ensure that each map conveys the intended story about public health data. This may require educating the content owner about the map options available in the WCMS. For more information on data classification and other data map options, see the WCMS instructions.

Tooltip / Modal Options

For desktop viewports, you can set the user interaction as follows:

  • Hover — Tooltip:  An on-hover action on a location displays a tooltip with the state/country data. If a navigation URL is provided, clicking takes the user directly to the associated URL.
  • Click — Popover Modal:  Clicking displays a modal with the state/country data. If a navigation URL is provided, the modal includes a “learn more” link for navigation.  This is the preferred option for navigation.

For examples of the two options, see example numeric maps.  The top example uses the click option, while the bottom example uses the hover option.

Note that all links — whether they’re in map tooltips or the data table — display with the standard external-link icon.  This icon is intended to let the user know that the linked content opens outside the data map.

Working with City Data

When including data for U.S. cities, follow these guidelines:

  • To confirm that a specific city is supported, check the list of 100 cities for data maps excel icon[XLS – 1 KB].
  • Double-check the spelling of all cities in the source data file. (Washington, DC, should be listed as “District of Columbia,” but it displays as Washington, DC, on the map and in the data table.)
  • If you are including multiple cities in the same metropolitan area, they may plot on top of one another in the map.  Make certain you are following 508 guidelines:
    • All data in the tooltips / modals should also be in the supporting data table.
    • If the map works as a navigation aid, include the URLs in the data table.

Color Palette / Ramp

Multiple maps:  All of the “intensity” color palettes have two versions:  light-to-dark and dark-to-light. If your site is presenting multiple related maps, consider the public health indicators when determining the map color palette / ramp.  (View palette options.) To ensure visual consistency and optimal usability across maps, you may need to “flip” the color ramp for one or more maps.

For example, compare the indicators “Percentage of adults who smoke daily” and “Percentage of adult smokers enrolled in a cessation program.” A higher number for the first indicator reflects a relatively negative outcome while a higher number for the second indicator reflects a relatively positive outcome. In the best cases the public health indicators have been formulated with color ramp direction in mind.  But if the data sources are varied, this may not be the case.

Categorical maps:  Like numeric maps, categorical maps can be based on an intensity scale (Never, OccasionallyEvery Month, Every Week, etc.). When there is no intensity scale (School, Home, Work, Vehicle, etc.), use one of the four “qualitative” color palettes. See example categorical maps.

Other Guidelines

  • Keep the map title as short as possible.  Use the map subtext for details.
  • Allow as much space as possible for each data map.
  • Don’t forget to explain special classes such as “NA.”  The map subtext is a good location for this information.
  • In most cases, four to five data classes work best, but as with the data classification schema, much depends on the public health message and the source data.
Go to Examples


To see examples of the different data classifications types, see the pages for numeric maps and categorical maps.

Other examples:

Page last reviewed: August 7, 2020
Content source: WCMS / Template Team