Data Map

Building in the WCMS


The configuration of a data map can highlight or obscure the public health messages the content owner is trying to convey.  It can also affect the usability of the map.  Before publishing a data map in the WCMS, make certain the owner is aware of the mapping options and work with the owner to design the map.  See Data Map Best Practices for more information.

The WCMS data map is a reusable component.  Once you create a data map, you can insert it into multiple pages or modules.

Note: With WCMS Release 4.9.12, the map editor is now in the new content type Data Visualization.

Data Requirements

To create a data-driven map, you need a CSV or JSON file containing a record for each of the geographic entities to be included in the map.  (If you are creating a filterable map, the source file should have multiple records for each geographic entity.  For example, if you are implementing a gender filter, the source file should have male and female records for all the geographic entities to be included.)  The data file must have the following columns:

  • A column for the geographic names / abbreviations
  • A column for the data to be color-coded in the map (can be numeric or categorical)

The file may also contain the following:

  • A column with URLs to geographic-specific information (e.g., state profiles), if map is to function as a navigation aid
  • Any additional columns to be included in the data table and/or the map tooltips / modal pop-ups

Example CSV files are available for download:

The data file must adhere to formatting standards as described below. Also, the spellings of the geographic entities must match those in the example CSV files.  (For U.S. states/territories, two-character postal codes are acceptable, but names are preferred.  The accepted abbreviations are included in the example U.S. data file above.  Note that abbreviations are not accepted for cities.)

Note that Excel may render the special characters in some country names incorrectly. Do not try to correct this issue.  The country names should import correctly into the map editor.

CSV Format

The CSV format must contain a header row naming the columns in the data. Each subsequent row must represent the state/territory data. Below is an example snippet of dummy data for flu prevalence:


You can easily generate data in CSV format from an Excel spreadsheet. Just save the spreadsheet as a comma-delimited CSV file. (In the “Save as type” drop-down, select “CSV (Comma delimited).”

Tip regarding special characters:   With CSV files produced in Excel, special characters (such as the equal sign) may display incorrectly as other characters upon upload into the WCMS.  If you encounter converted characters, use a plain-text editor such as Notepad to edit the CSV file and then try the upload again.

JSON Format

The example Flu prevalence data above are formatted as follows in JSON:


Creating the Map

  1. From the WCMS content browser, select “New Content” and then select “Data Visualization” (under “Media and Visualizations”) as the content type.
  2. Enter a title and a JSON file name.
  3. Then click Open Visualization Editor and complete the fields in the following sections.

Note that there are two tabs in the editor:  1. Import Data and 2. Configure.

Importing Data

In the Import Data tab, select “Local File” or “URL.” When loading from a URL, you can check  “Always Load from URL” to keep the data map in sync with the source data. This causes the map to load from the URL endpoint each time it is rendered.  Note:  If a URL is used, the host of the URL must be set to allow for cross-domain web requests.

Once the import has completed successfully, you can preview the data in the table on the right.

To proceed, click the “Configure” tab and proceed through the following panels.

General Panel

In the general panel select the Geography (United States or World) set the Map Type to “Data.”

Then edit the map title and subtext (the supporting text that displays below the data table) as appropriate.

Columns Panel

In the columns panel, describe your source data by completing the following information:

    • Geography (non-region maps only): Select the column in the CSV or JSON file that contains the geographic names/abbreviations. This column must comply with data map standards as explained in “Data Requirements” above.
    • Primary:  Select the data column to map and then complete the following fields.  (The source data may have multiple columns of data, but only one can be color-coded in the map visualization.  You can include other data in the data table and tooltips with the “Add Column” option.)
      • Label: Indicate the display label for the mapped data (if different from the source column header).
      • Prefix and Suffix:  Enter any special characters to display before and/or after the data (such as % or $).
      • Round:  If you wish to round decimal numbers, enter the number of decimal positions.
      • Display in Data Table:  Check this option to ensure that the mapped data also display in the supporting data table. Unless special 508 support is provided, this option should always be checked.  Leaving it unchecked can result in a major 508 violation.
      • Display in Tooltips:  Check this option to display the mapped data values in the tooltips.
screen cap of data map tooltip
      • Special Class Values:  If your mapped data include values such as “*” or “NA,” list these values, separated by commas. Up two to special values are supported. They are color-coded in shades of gray in the map visualization.
  • Navigation:  If the source data file includes URLs, you can add navigation by selecting the URL column.
  • Add Column:  The source data file may included data in addition to the values being mapped.  To add a column to the data table and/or the tooltips, click “Add Column” and then complete the information for the additional column.  Repeat as necessary until all additional columns you want to include are configured.

Note:  If you are building a categorical map — i.e., a non-numeric map — the map preview will not work correctly until you set the Legend Type to “Categorical” in the Legend panel.

Legend Panel

  • Legend Type:  Based on the type of data and the public health message, select how data classes are to be handled.  There are three options: the two numeric types “Equal Number (Quantiles)” and “Equal Interval” and a third type for text-based data called Categorical. To understand the uses of the two numeric types, see example numeric maps. For categorical data, see example categorical maps.
  • Number of Items (Equal Number or Equal Interval only): Select the number of data classes to display. Do not include special values such as * or NA.  They are automatically mapped in shades of gray.
  • Category Order: If you selected “categorical” as the Legend Type, you can drag and drop the categories into the appropriate order.  If the data classification is based on intensity (e.g., Rarely, Occasionally, Frequently, Very Frequently), place the values in order of intensity, from low to high or vice versa.  
  • Dynamic Legend Description: Check this option if you are using filters and you want to specify a description for each filter selection or combination of selections.  When this option is checked, select each filter option in the drop-down list below (e.g., “Gender – Female”) and enter a legend description for that combination.
  • Unified Legend:  If you are including one or more data filters and want the high and low values in the legend to be based on all mapped values, check this option. Otherwise, the legend high and low values are determined by the numeric range of the selected filter value set.
  • Legend Title and Legend Description:  Provide a brief title and description for the legend when necessary to complete the map description / instructions.
  • Separate Zero:  For numeric data, check this option to separate the value zero as its own data class.  When this option is checked, zero uses one of the colors in the map palette, so you may want to adjust the Number of Colors after checking this option. NOTE:  This legacy option is currently unavailable, but will be re-added in a future release.

Filters Panel

Click “Add Filter” to create a filter. Then select the column to filter on and provide a label. Repeat for each filter.

Data Table Panel

In the Data Table panel you can provide a custom title for the data table and indicate the default state of the data table (expanded or collapsed).  You can also enable/disable the “Download CSV” button.

Tooltips / Modals Panel

In the tooltips panel, select the “click” or “hover” option to specify how desktop users interact with the map.  For examples of the two options, see the numeric map examples.

Checking “Capitalize Text Inside Tooltip” turns on the auto-capitalization feature, which may create awkward capitalization in some cases (e.g., “Defining Area(S)”).  To capitalize text exactly as it appears in the source data, uncheck this option.

Visual Panel

Most of the fields in the Visual panel are self-explanatory, but the Map Color Palette requires a little explanation:  If the mapped data values fall along an intensity continuum, choose any of the color palettes not specified as “Qualitative.” Each of these color palettes has an array of colors from light to dark or dark to light.  If you do not want to show intensity, choose any of the “Qualitative” color palettes. View map color palettes.

Inserting the Map

Once you save the map, you can insert it into any page via Visual Composer or the WYSIWYG Editor.  Select “Data Visualization” when prompted.

WCMS Quick Facts

The geography column in the source data file must use approved state / country spellings.  See “Data Requirements” in the instructions on the left.

For the source data file, you can select a local file or you can enter a URL. If you enter a URL, you can check “Always Load from URL” to keep the map data in sync with the source data.

If a geographic entity has no data to map, leave it out of the data file.  Or use a special class value (such as “*” or “NA”).

For categorical maps based on an intensity scale, list the categories in the order of intensity, from high to low or low to high (Category Order  in Legend panel).

You can include filter controls based on or one or more columns.  If the data support filtering, in the Filters panel indicate the filtering column label and select the column for filtering.  In the Legend panel, you can check “Dynamic Legend Description” to specify a description for each filter set. See example filterable map.

The 100 most populous U.S. cities are supported.  See city list excel icon[XLS – 1 KB].

Page last reviewed: March 11, 2021
Content source: WCMS / Template Team