This website is for version 5. You can find the documentation for version 4 here.


mark_geoshape represents an arbitrary shapes whose geometry is determined by specified spatial data.

Geoshape Mark Properties#

A geoshape mark can contain any standard mark properties.

Basic Map#

Altair can work with many different geographical data formats, including geojson and topojson files. Often, the most convenient input format to use is a GeoDataFrame. Here we load the Natural Earth 110m Cultural Vectors dataset and create a basic map using mark_geoshape:

import altair as alt
from vega_datasets import data
import geopandas as gpd

url = ""
gdf_ne = gpd.read_file(url)  # zipped shapefile
gdf_ne = gdf_ne[["NAME", "CONTINENT", "POP_EST", 'geometry']]


In the example above, Altair applies a default blue fill color and uses a default map projection (equalEarth). We can customize the colors and boundary stroke widths using standard mark properties. Using the project method we can also define a custom map projection manually:

    fill='lightgrey', stroke='white', strokeWidth=0.5

Focus & Filtering#

By default Altair automatically adjusts the projection so that all the data fits within the width and height of the chart. Multiple approaches can be used to focus on specific regions of your spatial data. Namely:

  1. Filter the source data within your GeoDataFrame.

  2. Filter the source data using a transform_filter.

  3. Specify scale (zoom level) and translate (panning) within the project method.

  4. Specify fit (extent) within the project & clip=True in the mark properties.

The following examples applies these approaches to focus on continental Africa:

  1. Filter the source data within your GeoDataFrame:

gdf_sel = gdf_ne.query("CONTINENT == 'Africa'")

  1. Filter the source data using a transform_filter:

    alt.datum.CONTINENT == 'Africa'