Map visualizations

The map visualizations display results on a geographic map. The query result set must include the appropriate geographic data:

• Choropleth: Geographic localities, such as countries or states, are colored according to the aggregate values of each key column. The query must return geographic locations by name or as a GEOMETRY or GEOGRAPHY column. For an example, see choropleth example.
• Point map: A marker is placed at a set of coordinates on the map. The query result must return latitude and longitude pairs or a GEOMETRY or GEOGRAPHY column. For an example, see marker example.

You can also render shapes from a GEOMETRY or GEOGRAPHY column instead of relying on predefined administrative boundaries or separate latitude and longitude columns. See Custom geographic data.

Choropleth options

A choropleth map colors geographic regions — such as countries, states, or counties — based on a numeric value in your data.

Example

In the Data tab, click + Add SQL dataset, paste the following query, and run it:

SELECT state, total_sales
FROM VALUES
  ('California', 98750),
  ('Texas', 87200),
  ('New York', 76300),
  ('Florida', 65100),
  ('Illinois', 54800),
  ('Pennsylvania', 48200),
  ('Ohio', 43500),
  ('Georgia', 41200),
  ('North Carolina', 39700),
  ('Michigan', 36100),
  ('New Jersey', 34800),
  ('Virginia', 32500),
  ('Washington', 31200),
  ('Arizona', 29700),
  ('Massachusetts', 28400),
  ('Tennessee', 26900),
  ('Indiana', 25100),
  ('Missouri', 23800),
  ('Maryland', 22600),
  ('Wisconsin', 21300),
  ('Minnesota', 20100),
  ('Colorado', 19400),
  ('Alabama', 18200),
  ('South Carolina', 17600),
  ('Louisiana', 16900),
  ('Kentucky', 15800),
  ('Oregon', 14700),
  ('Oklahoma', 13600),
  ('Connecticut', 12500),
  ('Utah', 11900),
  ('Iowa', 11200),
  ('Nevada', 10800),
  ('Arkansas', 10100),
  ('Mississippi', 9600),
  ('Kansas', 9200),
  ('New Mexico', 8700),
  ('Nebraska', 8300),
  ('West Virginia', 7900),
  ('Idaho', 7400),
  ('Hawaii', 7100),
  ('New Hampshire', 6800),
  ('Maine', 6400),
  ('Montana', 6100),
  ('Rhode Island', 5800),
  ('Delaware', 5400),
  ('South Dakota', 5100),
  ('North Dakota', 4800),
  ('Alaska', 4500),
  ('Vermont', 4200),
  ('Wyoming', 3900)
AS t(state, total_sales);

In the visualization editor, configure the following:

1. Set the visualization type to Choropleth map.
2. In the Region section, under Country, click the plus icon. Under Values, click Select a country and select United States.
3. In the Region section, under State/Province click the plus icon. Under Fields, select state.
4. Under Color, click the plus icon, select total_sales, and set the transform to SUM.

Region

The Region setting tells the map how to interpret the location values in your data. Choose the format that matches your data:

• Administrative: Country, State/Province, County/City, Town/Township, or City/Village
• Postal: ZIP or postal codes.
• CSA / CSAB: US Census Bureau statistical area designations. CSA (Combined Statistical Areas) groups adjacent metropolitan and micropolitan areas with economic ties. CBSA (Core Based Statistical Areas) covers individual metropolitan and micropolitan areas.
• Legislative: U.S. legislative districts, including congressional districts and state senate districts.
• NUTs: EU Nomenclature of Territorial Units for Statistics. Supports three levels: NUTS 1 (major socioeconomic regions), NUTS 2 (basic regions for applying regional policies), and NUTS 3 (small regions for specific diagnoses).
• Custom geometry: Select a GEOMETRY or GEOGRAPHY column to render region boundaries directly from your data. See Custom geographic data.

If a value in your location column doesn't match the selected format, no data is shown for that region. Download the following lookup tables to check which names and abbreviations are supported:

• country-names.csv
• state-province-names.csv
• county-district-names.csv
• town-names.csv
• city-village-names.csv
• senate-names.csv
• congressional-district-codes.csv
• zipcode-codes.csv
• us-csa-codes.csv
• us-cbsa-codes.csv
• eu-nuts-1-codes.csv
• eu-nuts-2-codes.csv
• eu-nuts-3-codes.csv

Colors

Colors populate automatically for each region that has data. Click the color swatch to choose a different color.

To color regions by a numeric field, click the plus icon in the Color section and select a field. You can apply a transformation such as SUM or MEDIAN. The map applies a color gradient across the range of values. To customize the colors, gradient, and labels, click the color swatch.

Point map options

This section describes options for point map charts.

Example

In the Data tab, click + Add SQL dataset, paste the following query, and run it:

SELECT city, latitude, longitude, population
FROM VALUES
  ('New York',     40.7128,  -74.0060, 8336817),
  ('Los Angeles',  34.0522, -118.2437, 3979576),
  ('Chicago',      41.8781,  -87.6298, 2693976),
  ('Houston',      29.7604,  -95.3698, 2320268),
  ('Phoenix',      33.4484, -112.0740, 1608139),
  ('Philadelphia', 39.9526,  -75.1652, 1603797),
  ('San Antonio',  29.4241,  -98.4936, 1434625),
  ('San Diego',    32.7157, -117.1611, 1386932),
  ('Dallas',       32.7767,  -96.7970, 1304379),
  ('San Jose',     37.3382, -121.8863, 1013240)
AS t(city, latitude, longitude, population);

In the visualization editor, configure the following:

1. Under Coordinates, select Longitude/Latitude.
   1. Under Longitude, click plus icon and select longitude.
   2. Under Latitude, click plus icon and select latitude.
2. Under Size, click plus icon and select population.

Coordinates

Use the visualization editor to configure the Coordinates:

• Longitude/Latitude: Choose the column that contains the Longitude and Latitude components of the map coordinates.
• Geometry: Select a GEOMETRY or GEOGRAPHY column to use as the point location instead of separate latitude and longitude columns. See Custom geographic data.

Color

For ungrouped data, click the color swatch to change the point colors shown on the map. To apply a grouping strategy, click plus icon in the Color section of the visualization editor. You can adjust the automatically assigned colors by clicking the color swatch next to each group label in the editor.

Size

Click plus icon in the Size section to choose a field that reflects quantity, allowing you to display dots of varying sizes based on the data value.

Custom geographic data

You can render maps directly from a GEOMETRY or GEOGRAPHY column in any dataset. Use this to visualize custom shapes such as sales territories, school districts, and store catchment areas, or to plot points without splitting coordinates into separate latitude and longitude columns.

Each row is drawn independently, so shapes or points may overlap if your data has multiple rows per region. To combine rows into a single shape per region, use a geometry measure in a metric view. See Limitations and Local metric views.

Define a metric view with a geometry measure

In your metric view YAML, set the geometry or geography column as a measure using one of the supported aggregations: ST_UNION_AGG, ST_ENVELOPE_AGG, FIRST, or LAST. Use dimensions for the non-geometry columns you want to group by.

The following local metric view defines region as a dimension, total_sales as a numeric measure, and uses ST_UNION_AGG to combine per-row boundaries into a single shape per region:

version: 0.1
source: sales.territories

dimensions:
  - name: region
    expr: region

measures:
  - name: total_sales
    expr: SUM(sales_amount)
  - name: region_shape
    expr: ST_UNION_AGG(boundary)

If your geographic data is stored as a serialized string or binary value, cast it to GEOMETRY or GEOGRAPHY in the measure expression.

Create a choropleth map

Choropleth maps support Polygon and MultiPolygon shapes.

1. Add the metric view as a dataset.
2. Set the visualization type to Choropleth map.
3. Under Region, select Custom geometry and select your geometry measure (for example, region_shape).
4. Under Color, select a numeric measure such as total_sales.

Create a point map

Point maps support Point and MultiPoint shapes. Use a Point-valued geometry measure such as FIRST(location) or ST_UNION_AGG(location).

1. Add the metric view as a dataset.
2. Set the visualization type to Point map.
3. Under Coordinates, select Geometry and select your geometry measure.
4. (Optional) Under Size, select a numeric measure to vary point sizes.

Limitations

• GROUP BY isn't supported on GEOMETRY or GEOGRAPHY columns. To combine multiple rows into a single shape per group, aggregate geometry as a metric view measure using ST_UNION_AGG, ST_ENVELOPE_AGG, FIRST, or LAST. Otherwise, each row is rendered independently and shapes may overlap.
• The map renderer uses WGS84 (SRID 4326). GEOMETRY columns in other SRIDs are reprojected automatically; GEOGRAPHY columns must already be SRID 4326. Use ST_Transform in your measure expression to reproject if needed.
• GEOMETRY columns with SRID 0 (unknown coordinate system) aren't rendered.
• GeometryCollection values and columns that mix multiple shape types aren't supported.
• Label encodings aren't supported on maps that use a geometry or geography column.