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 – U.S. and world  and WCMS instructions – county level.


Use a data map to display geographically color-coded numeric or categorical data.  A data map can also 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.)

U.S. Choropleth vs. Hex-Tile Maps

For U.S. data, the WCMS supports both choropleth and hex-tile maps (also called “hex-grid maps” or simply “hex maps”).

Screenshots of choropleth and hex-tile maps of U.S.

Generally, use choropleth maps when geographic precision is key to the public health message — for example, to show a geographic trend or to highlight geographic variation. They are intuitive and work well for presenting at-a-glance information.  (You should also use choropleth maps when city data are being mapped. Hex-tile maps do not support cities.)

When geography isn’t important to the message or when there is concern about the “Alaska effect” (the possible misperception of data due to the great surface area of some low-population states), the hex-tile map offers benefits over the choropleth map:

  • The hex-tile map allows viewers to see the colors and labels of the smallest states as easily as the largest states.
  • If a map serves as a navigation aid to information such as state profiles, hex tiles may be preferred because they make interaction with small states easier.
  • The hex-tile map is a good solution when the goal is to present simple yes / no data (for example, the states where a certain public health policy is in effect or the states that have reached a certain threshold).

Normalized vs. Non-Normalized Data

Data maps typically show normalized data (such as percentages or per-capita numbers). Due to the vast population differences among geographic areas, non-normalized data may be misleading. But there is an exception:  if the goal is to show where the largest numbers of people can be reached for public health interventions, non-normalized data may be more useful.

Special Classes

For states or countries with values such as “*” or “NA,” you can specify these values as “special classes” (i.e., special data classes). The map tool automatically color-codes these special classes with shades of gray, one for each special class. For optimal usability, avoid having more than two special classes on a 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.


Filters in COVE can be configured with a parameter that can be used to pre-set filter values upon loading a page.  For example, on the Filterable Data Maps example page:

  • The Year filters in both maps are set by “filter1” in the URL
  • The Sex filter is set by “filter2”
  • The Age filter is set by “filter3”

So /wcms/4.0/cdc-wp/data-presentation/examples/example-numeric-maps-filterable.html?filter1=2017&filter2=Male&filter3=55-64 will load that page with those specific values set.  Click on the link to try it out.

Setting filters will also set the value in the parameter, so that after setting the maps how they are desired, the URL on the page can be shared to present the data as it was viewed.

The filter parameter value can be configured where the filters are configured for Maps, Charts, and Dashboards.

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 cities supported by the U.S. data map [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 on 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.

Working with County Data

When including data for counties, follow these guidelines:

  • A FIPS number is required for each county.  FIPS stands for Federal Information Processing Standards.
  • For an example of Data Formatting, use this file Sample County Level Data [CSV – 112 KB].
  • Make sure FIPS Code for each county contains the full 5 characters. States like Alaska may drop the lead zero when imported into Excel as a spreadsheet.  Formatting the cells as “custom” from the category list and then overwriting the general option with  “00000” will add the leading 0 back to any number.  The data must then be exported as a .CSV file type to retain the numbers for use in the editor.
  • Make sure to set County Census Year in the General Panel, as some county lines shift over time. If you are using the map to display multiple years of data, you can add your Year filter to sort the Filter Controlling County Census Year once it has been configured.

Color Palette / Ramp

All of the “intensity” color palettes have two versions:  light-to-dark and dark-to-light. When selecting a color palette, keep in mind that viewers typically associate darker shades with greater frequency or intensity.

Multiple maps:  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.


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

Other examples: