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'.

For a visual example of how a map projection changes the apparent size of countries, try Tiny to Vast's True Size of Countries map (opens in a new tab).

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

Data Computation Chart Export