Map Charts¶

Dataface supports geographic map visualizations including choropleth maps (filled regions), point maps (markers), and bubble maps (sized markers). Maps are rendered using Vega-Lite's geoshape capabilities.

Map Types¶

Type	Description	Best For
`choropleth`	Filled regions colored by data	State/country-level metrics
`point_map`	Markers at lat/lng coordinates	Location plotting
`bubble_map`	Sized circles at coordinates	Location + magnitude

Choropleth Maps¶

Best for: Visualizing metrics by geographic region (states, countries, counties)

Choropleth maps color geographic regions based on data values. You provide data with a key field (like state ID or country code) that joins to the geographic boundaries.

queries:
  state_data:
    type: csv
    file: assets/data/us_states.csv
charts:
  population_map:
    title: "US Population by State"
    type: choropleth
    query: state_data
    geo_source: us-states
    lookup: id
    value: population
    projection: albersUsa
    style:
      color_scheme: blues
rows:
  - population_map

▶

Field	Required	Description
`geo_source`	Yes	Geographic data source (see below)
`lookup`	Yes	Field in your data to join with geo data
`value`	Yes	Field to use for coloring regions
`projection`	No	Map projection (default based on geo_source)

Point Maps¶

Best for: Plotting individual locations on a map

Point maps place markers at specific latitude/longitude coordinates.

charts:
  locations:
    title: "Office Locations"
    type: point_map
    query: offices
    latitude: lat
    longitude: lng
    color: region           # Optional: color by category
    projection: albersUsa
    geo_source: us-states   # Optional: background map

Field	Required	Description
`latitude`	Yes	Field containing latitude values
`longitude`	Yes	Field containing longitude values
`color`	No	Field to color markers by
`geo_source`	No	Background map (optional)

Bubble Maps¶

Best for: Showing magnitude at locations (e.g., revenue by city)

Bubble maps extend point maps with sized circles proportional to a value.

queries:
  stores:
    type: csv
    file: assets/data/store_locations.csv
charts:
  store_map:
    title: "Store Locations by Revenue"
    type: bubble_map
    query: stores
    latitude: latitude
    longitude: longitude
    size: revenue
    color: store_type
    projection: albersUsa
    geo_source: us-states
rows:
  - store_map

▶

Field	Required	Description
`latitude`	Yes	Field containing latitude values
`longitude`	Yes	Field containing longitude values
`size`	Yes	Field to size bubbles by
`color`	No	Field to color bubbles by
`geo_source`	No	Background map (optional)

Geographic Sources¶

Dataface includes built-in geographic data sources:

National & World Boundaries¶

Source	Description	Key Field	Default Projection
`us-states`	US state boundaries	`id` (FIPS code)	`albersUsa`
`us-counties`	US county boundaries	`id` (FIPS code)	`albersUsa`
`world-countries`	World country boundaries	`id` (numeric code)	`equalEarth`
`world-50m`	Simplified world map	`id` (numeric code)	`equalEarth`

City Neighborhoods¶

Dataface includes built-in presets for popular US cities with pre-configured projections:

Source	Description	Key Field	Data Source
`sf-neighborhoods`	San Francisco neighborhoods	`nhood`	SF Open Data
`nyc-neighborhoods`	NYC neighborhood tabulation areas	`ntaname`	NYC Open Data
`chicago-neighborhoods`	Chicago community areas	`pri_neigh`	Chicago Data Portal
`la-neighborhoods`	Los Angeles neighborhoods	`name`	LA GeoHub

City maps come with optimized mercator projections with center and scale pre-configured for each city.

US State FIPS Codes¶

For us-states, the id field expects numeric FIPS codes:

State	FIPS	State	FIPS
Alabama	1	Montana	30
Alaska	2	Nebraska	31
Arizona	4	Nevada	32
California	6	New York	36
Colorado	8	Texas	48
...	...	...	...

See FIPS code reference for the complete list.

Custom Geographic Data¶

You can also use custom GeoJSON/TopoJSON URLs:

charts:
  custom_map:
    type: choropleth
    query: my_data
    geo_source: "https://example.com/my-boundaries.json"
    lookup: region_id
    value: metric

Projections¶

Map projections control how the spherical earth is displayed on a flat surface. Available projections:

Projection	Description	Best For
`albersUsa`	US-optimized with Alaska/Hawaii insets	US maps
`equalEarth`	Equal-area, minimal distortion	World maps
`mercator`	Standard web map projection	General use
`naturalEarth1`	Compromise projection	World maps
`orthographic`	Globe view	Presentations
`stereographic`	Polar regions	Arctic/Antarctic
`albers`	Conic equal-area	Mid-latitudes
`conicEqualArea`	Conic equal-area	Specific regions
`equirectangular`	Simple plate carrée	Data exchange

Example: World Map with equalEarth¶

charts:
  world_gdp:
    title: "GDP by Country"
    type: choropleth
    query: country_data
    geo_source: world-countries
    lookup: country_id
    value: gdp
    projection: equalEarth
    style:
      color_scheme: viridis

Data Joining¶

Maps join your data to geographic features using a lookup field. The lookup transform matches values in your data with keys in the geographic data.

How It Works¶

Your data has a key field (e.g., state_id: 6 for California)
The geographic data has matching keys (e.g., id: 6)
The lookup field specifies which field in your data to use for matching

# Your query returns data like:
# state_id | population
# 6        | 39538223    (California)
# 48       | 29145505    (Texas)

charts:
  pop_map:
    type: choropleth
    query: state_population
    geo_source: us-states
    lookup: state_id        # Matches to geo data's "id" field
    value: population

Key Field Formats¶

The system normalizes common key formats:

Format	Example	Normalization
FIPS codes	`"6"`, `"06"`	Zero-padding handled
ISO country codes	`"usa"`, `"USA"`	Case-normalized
State abbreviations	`"ca"`, `"CA"`	Case-normalized
State names	`"california"`	Title-cased

Handling Missing Data¶

Regions without matching data are displayed in a neutral gray color. This makes it clear which areas have data vs. which are missing.

Color Schemes¶

Use the style.color_scheme property to set the color palette:

charts:
  my_map:
    type: choropleth
    # ... other config ...
    style:
      color_scheme: blues    # Sequential blue palette

Recommended Schemes for Maps¶

Scheme	Type	Best For
`blues`	Sequential	Single-hue metrics
`greens`	Sequential	Environmental data
`oranges`	Sequential	Warm tone metrics
`viridis`	Sequential	General purpose, colorblind-safe
`plasma`	Sequential	High contrast
`redblue`	Diverging	Positive/negative values
`spectral`	Diverging	Deviation from center

City-Level Maps¶

City neighborhoods are perfect for local analytics like real estate, demographics, or crime mapping. Dataface includes built-in presets for major US cities.

San Francisco Neighborhoods¶

title: SF Demographics

queries:
  sf_data:
    type: csv
    file: assets/data/sf_neighborhoods.csv

charts:
  income_map:
    title: "Median Income by Neighborhood"
    type: choropleth
    query: sf_data
    geo_source: sf-neighborhoods  # Built-in SF preset
    lookup: nhood                  # Matches neighborhood name
    value: median_income
    style:
      color_scheme: viridis

rows:
  - chart: income_map
    height: 400

The sf-neighborhoods preset automatically configures:

GeoJSON URL from SF Open Data
Mercator projection centered on San Francisco
Appropriate zoom scale for the city

NYC Neighborhoods¶

charts:
  population_map:
    title: "NYC Population by Neighborhood"
    type: choropleth
    query: nyc_data
    geo_source: nyc-neighborhoods  # Built-in NYC preset
    lookup: ntaname                 # Neighborhood Tabulation Area name
    value: population
    style:
      color_scheme: greens

Custom City Maps¶

For cities not in the preset list, use a custom GeoJSON URL with projection configuration:

charts:
  custom_city:
    title: "Boston Neighborhoods"
    type: choropleth
    query: boston_data
    geo_source: "https://data.boston.gov/dataset/boston-neighborhoods/..."
    lookup: name
    value: metric
    projection:
      type: mercator
      center: [-71.0589, 42.3601]  # Boston coordinates
      scale: 60000

Finding City GeoJSON Data¶

Most cities publish neighborhood boundaries through open data portals:

City	Data Portal
San Francisco	data.sfgov.org
New York	data.cityofnewyork.us
Chicago	data.cityofchicago.org
Los Angeles	geohub.lacity.org
Boston	data.boston.gov
Seattle	data.seattle.gov

Search for "neighborhoods", "community areas", or "districts" and export as GeoJSON.

Complete Examples¶

US Sales by State¶

title: Regional Sales Dashboard

queries:
  sales_by_state:
    sql: |
      SELECT state_fips as id, SUM(amount) as total_sales
      FROM orders
      GROUP BY state_fips

charts:
  sales_map:
    title: "Total Sales by State"
    type: choropleth
    query: sales_by_state
    geo_source: us-states
    lookup: id
    value: total_sales
    projection: albersUsa
    style:
      color_scheme: blues

rows:
  - chart: sales_map
    height: 500

Store Locations with Revenue¶

title: Store Network

queries:
  stores:
    sql: SELECT name, lat, lng, revenue, type FROM stores

charts:
  store_map:
    title: "Store Locations"
    type: bubble_map
    query: stores
    latitude: lat
    longitude: lng
    size: revenue
    color: type
    projection: albersUsa
    geo_source: us-states

rows:
  - chart: store_map
    height: 500

World Population¶

title: Global Population

queries:
  population:
    sql: SELECT country_code as id, population FROM countries

charts:
  world_pop:
    title: "World Population"
    type: choropleth
    query: population
    geo_source: world-countries
    lookup: id
    value: population
    projection: equalEarth
    style:
      color_scheme: viridis

rows:
  - chart: world_pop
    height: 400

SF Neighborhood Analytics¶

title: San Francisco Real Estate

queries:
  neighborhoods:
    sql: |
      SELECT neighborhood as nhood, 
             AVG(price) as avg_price,
             COUNT(*) as listings
      FROM real_estate
      GROUP BY neighborhood

charts:
  price_map:
    title: "Average Home Price by Neighborhood"
    type: choropleth
    query: neighborhoods
    geo_source: sf-neighborhoods
    lookup: nhood
    value: avg_price
    style:
      color_scheme: plasma

rows:
  - chart: price_map
    height: 400

Terminal Mode¶

Maps cannot be rendered in terminal mode. When using face render --terminal, map charts fall back to displaying a data table instead.

Chart Types - Common chart types
More Types - All Vega-Lite marks
Styling - Color schemes and themes
Queries - Data sources for charts