Maps

Maps encode data through geographic position, using region fills, symbols, or other marks tied to real places. They are most useful when location itself is part of the meaning, with filled-region maps working best for values aggregated by area and symbol maps working best for counts, events, or magnitudes at specific places.

Dataface maps are configured primarily through top-level geographic fields such as geo, geo_source, lookup, value, projection, latitude, longitude, size, and background. In practice, that means this family relies much more on map-specific top-level configuration than on large mark, encoding, or style passthrough surfaces.

A chart's control surface is the full set of authored properties available on a single chart. In Dataface, that surface is primarily top-level chart fields plus the typed style object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the Single-Chart Property Catalog.

Map joins are exact-key joins. Your lookup field must match the geographic source's key values exactly, including formatting details such as leading zeros, abbreviations, or code systems. If a region is unexpectedly missing, the first thing to check is whether the query key format matches the map source key format.

---

Minimum Required for a Filled-Region Map

These are the minimum fields required to render a basic filled-region map in Dataface. Other map forms have different minimums: a symbol map (type: point_map) needs coordinate fields, and a proportional symbol map (type: bubble_map) needs coordinates plus a size field. projection is optional for all of them because Dataface uses a source-appropriate default when you do not specify one.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
query	lookup data values	Query name or query reference	Supplies the data that will be joined to the geographic features.
type: map	mark.type: "geoshape"	Literal map	Selects the filled-region map form. (type: choropleth is accepted as an alias.)
geo.source	geographic data URL and format	Built-in geo source name or custom GeoJSON/TopoJSON URL	Chooses the boundary shapes to render.
lookup	geoshape lookup join key	Field name	Field in your query data that joins to the geographic source. The values must match the source key format exactly.
value	encoding.color.field	Field name	Quantitative field used to fill regions. Prefer densities, rates, or percentages over raw totals.

Minimum Map Example

queries:
  new_england_population_density:
    columns: [state_code, population_density]
    values:
      - ["9", 742]
      - ["23", 44]
      - ["25", 901]
      - ["33", 154]
      - ["44", 1022]
      - ["50", 68]

charts:
  new_england_population_density_map:
    query: new_england_population_density
    type: map
    title: New England Population Density
    geo:
      source: us-states
    lookup: state_code
    value: population_density
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_population_density_map

▶

---

Top-Level Chart Fields

These are the top-level chart properties you set directly on a map before reaching for smaller nested properties. This is where Dataface exposes most of the meaningful map surface.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
query	lookup data values	Query name or query reference	Data to join to regions or plot as points.
type: map	mark.type: "geoshape"	Literal map	Canonical map type. Renders an outline map or a filled-region map depending on the fields provided. (type: choropleth is accepted as an alias.)
type: point_map	mark.type: "circle"	Literal point_map	Symbol map for events or places at exact coordinates.
type: bubble_map	mark.type: "circle"	Literal bubble_map	Proportional symbol map with quantitative sizing.
title	title.text	String	Chart title.
description	metadata	String	Available for tooling and docs.
geo	geographic source config	Object with source, optional key, optional feature	Primary map source config.
geo_source	geographic source selector	us-states, us-counties, world-countries, world-50m, sf-neighborhoods, nyc-neighborhoods, chicago-neighborhoods, la-neighborhoods	Convenience shorthand for selecting a built-in background or map source.
lookup	geoshape lookup join key	Field name	Query field used to join your data to the geographic features. The values must match the source key format exactly.
value	encoding.color.field	Field name	Region fill value field. In practice, filled-region maps usually work best with densities, rates, or percentages rather than raw totals.
color	encoding.color.field	Field name	Bubble/point color field, or region fill shorthand when value is omitted.
projection	top-level projection	mercator, albersUsa, equalEarth, naturalEarth1, orthographic, stereographic, albers, conicEqualArea, equirectangular, or projection object	Overrides the source default projection.
latitude	encoding.latitude.field	Field name	Point-map latitude field. Auto-detected from common names when omitted.
longitude	encoding.longitude.field	Field name	Point-map longitude field. Auto-detected from common names when omitted.
size	encoding.size.field	Field name	Quantitative size field for bubble maps.
background	layered background geoshape config	Object with source, optional fill, optional stroke	Adds a background geography behind point or bubble maps.

Map Form Minimums

This quick reference shows the minimum fields for each major map form. Use it to choose the right starting shape before you add projection, color schemes, or other refinements.

Map form	Minimum Dataface fields	Notes
map	query, type: map, geo.source, lookup, value	Filled-region map joined to geographic features. (type: choropleth is accepted as an alias.)
map (outline)	type: map, geo.source	Base outline map. Add query, lookup, and value only if you want data-driven fills.
point_map	query, type: point_map, latitude, longitude	Symbol map for exact locations. Add geo_source or background if you want a geographic backdrop.
bubble_map	query, type: bubble_map, latitude, longitude, size	Proportional symbol map with quantitative sizing. Add geo_source or background if you want a geographic backdrop.

Filled-Region Maps and Bubble Maps

This example shows the family's two main forms using the same New England geography: a filled-region map for region-level density and a bubble map for magnitudes at exact locations.

queries:
  new_england_population_density:
    columns: [state_code, population_density]
    values:
      - ["9", 742]
      - ["23", 44]
      - ["25", 901]
      - ["33", 154]
      - ["44", 1022]
      - ["50", 68]

  new_england_cities:
    columns: [city, lat, lng, revenue, store_type]
    values:
      - ["Boston", 42.3601, -71.0589, 980000, "Flagship"]
      - ["Providence", 41.8240, -71.4128, 520000, "Boutique"]
      - ["Portland", 43.6591, -70.2568, 410000, "Boutique"]
      - ["Hartford", 41.7658, -72.6734, 460000, "Outlet"]
      - ["Burlington", 44.4759, -73.2121, 290000, "Boutique"]
      - ["Manchester", 42.9956, -71.4548, 380000, "Outlet"]

charts:
  new_england_population_density_map:
    query: new_england_population_density
    type: map
    title: New England Population Density
    geo:
      source: us-states
    lookup: state_code
    value: population_density
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200

  new_england_revenue_bubbles:
    query: new_england_cities
    type: bubble_map
    title: New England Store Revenue by City
    latitude: lat
    longitude: lng
    size: revenue
    color: store_type
    geo_source: us-states
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_population_density_map
  - new_england_revenue_bubbles

▶

Symbol Maps with a Regional Backdrop

This example shows how a regional symbol map can reuse the same New England projection without requiring proportional sizing.

queries:
  new_england_locations:
    columns: [name, lat, lng, location_type]
    values:
      - ["Boston", 42.3601, -71.0589, "Commercial Core"]
      - ["Portland", 43.6591, -70.2568, "Port City"]
      - ["Providence", 41.8240, -71.4128, "College City"]
      - ["Burlington", 44.4759, -73.2121, "Regional Hub"]

charts:
  new_england_point_map:
    query: new_england_locations
    type: point_map
    title: New England City Locations
    geo_source: us-states
    latitude: lat
    longitude: lng
    color: location_type
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_point_map

▶

---

Style Fields

Use style for map presentation properties that are intentionally simpler than full Vega-Lite control.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
style.color_scheme	encoding.color.scale.scheme	Vega-Lite color-scheme name	Most relevant for filled-region maps, where the fill scale carries the main value encoding.
style.background	chart SVG background wrapper	Color value	Applies a chart-level background fill behind the final rendered map SVG. Distinct from top-level background, which adds a geographic background layer for point and bubble maps.

Color Scheme

This example keeps the same New England geography and join logic fixed while changing the map palette.

queries:
  new_england_unemployment:
    columns: [state_code, unemployment]
    values:
      - ["9", 4.1]
      - ["23", 3.6]
      - ["25", 4.3]
      - ["33", 3.2]
      - ["44", 4.0]
      - ["50", 2.8]

charts:
  new_england_unemployment_map:
    query: new_england_unemployment
    type: map
    title: New England Unemployment Rate
    geo:
      source: us-states
    lookup: state_code
    value: unemployment
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
    style:
      color_scheme: viridis
rows:
  - new_england_unemployment_map

▶

---

Related

• Charts Overview
• Sector Charts
• Point Charts