Geographic Visualization

Graphic Walker supports two types of geographic visualizations: choropleth maps (colored regions) and point maps (markers at coordinates). Both require setting the coordinate system to 'geographic'.

Choropleth Maps

Choropleth maps color geographic regions based on data values. You need:

A GeoJSON or TopoJSON file defining region boundaries
A field in your data that matches region IDs in the geo data

Using the `geographicData` Prop

Pass geographic data directly:

import { GraphicWalker } from '@kanaries/graphic-walker';
 
const geoData = await fetch('/us-states.geojson').then(r => r.json());
 
<GraphicWalker
  data={salesByState}
  fields={fields}
  geographicData={{
    type: 'GeoJSON',
    data: geoData,
    key: 'name',  // property in GeoJSON features to match against
  }}
/>

In the chart configuration, set coordSystem: 'geographic' and geoms: ['choropleth'], then drag the state field to the geoId channel and a measure to the color channel.

Using the `geoList` Prop

Provide a list of geographic datasets that users can choose from in the UI:

<GraphicWalker
  data={data}
  fields={fields}
  geoList={[
    {
      type: 'GeoJSON',
      name: 'US States',
      url: 'https://example.com/us-states.geojson',
    },
    {
      type: 'TopoJSON',
      name: 'World Countries',
      url: 'https://example.com/world-110m.json',
    },
  ]}
/>

TopoJSON Support

TopoJSON files are more compact than GeoJSON. Specify the objectKey to select which layer to use:

<GraphicWalker
  data={data}
  fields={fields}
  geographicData={{
    type: 'TopoJSON',
    data: topoData,
    key: 'id',
    objectKey: 'countries',  // defaults to the first key in topology.objects
  }}
/>

Point Maps (POI)

Point maps display data as markers at geographic coordinates. Your data needs longitude and latitude fields.

In the chart config, set coordSystem: 'geographic' and geoms: ['poi'], then encode longitude and latitude fields in the corresponding channels.

const data = [
  { city: 'New York', lng: -74.006, lat: 40.7128, population: 8336817 },
  { city: 'Los Angeles', lng: -118.2437, lat: 34.0522, population: 3979576 },
];
 
const fields = [
  { fid: 'city', name: 'City', semanticType: 'nominal', analyticType: 'dimension' },
  { fid: 'lng', name: 'Longitude', semanticType: 'quantitative', analyticType: 'dimension' },
  { fid: 'lat', name: 'Latitude', semanticType: 'quantitative', analyticType: 'dimension' },
  { fid: 'population', name: 'Population', semanticType: 'quantitative', analyticType: 'measure' },
];

Custom Map Tiles

Customize the base map tile URL via the geoMapTileUrl property in IVisualLayout:

<GraphicWalker
  data={data}
  fields={fields}
  defaultConfig={{
    layout: {
      geoMapTileUrl: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
    },
  }}
/>

Layout Options for Maps

Property	Type	Description
`scaleIncludeUnmatchedChoropleth`	`boolean`	Include unmatched regions in the color scale
`showAllGeoshapeInChoropleth`	`boolean`	Show all geographic shapes even without matching data
`geoMapTileUrl`	`string`	Custom map tile URL template
`geoUrl`	`{ type: 'GeoJSON' \| 'TopoJSON'; url: string }`	URL to load geographic data from
`geoKey`	`string`	Property key to match data against features