Skip to main content
Omni’s region maps ship with built-in boundaries for countries and US states. However, the possibilities for regions you may want to visualize are multitudinous - zip codes in South America, voting districts in Australia and New Zealand, or a map showing both Canadian provinces and US states, which this guide will use as an example. When you want to display a custom set of regions, you can source them from your own GeoJSON. If you can find pre-existing GeoJSON files for the geographies you need, an AI coding tool can do the tedious part: merging separate boundary files into one, with a shared property to join against your specific dataset.

When to use this pattern

Use this pattern when the regions in your dataset don’t fit any single built-in map type. Examples:
  • A dataset with both US and Canadian locations, where you want one map instead of two.
  • A custom sales territory map built from several source boundary files, such as states grouped into regions.
  • Any geography a third-party GeoJSON source defines that Omni doesn’t offer natively.

Requirements

To follow the steps in this guide, you’ll need:
  • Restricted Querier or higher permissions, to configure a region map’s visualization settings.
  • An AI coding tool, such as Claude Code, to merge the GeoJSON files.
  • A place to host the combined file with CORS-enabled raw access, such as a public GitHub repository.
  • A dataset field with matching values, like a 2-letter region code, to join your data against the merged boundaries.

Steps

1

Gather boundary files

Find a GeoJSON source for each geography you want to combine. For example, a Canadian provinces GeoJSON file and a US states GeoJSON file. Download both into the same local directory.
2

Merge the files with AI

Prompt your AI coding tool to combine the files into a single FeatureCollection and add a shared property you can join against your dataset. For example:
Prompt used to merge CA provinces and US states
The property name has to match a field in your dataset. In this example, short_name pairs with a column of 2-letter state and province codes. Ask the AI tool to verify the merged file is valid GeoJSON before moving on.
3

Host the combined file

Omni loads custom region data from a URL, so the merged file needs to be hosted somewhere with CORS-enabled raw access, such as a public GitHub repository.Commit the file and use its raw file URL. For example:
4

Configure the custom region map in Omni

Completed example

exploreomni/geo-data is a public example of this pattern: a GeoJSON file combining Canadian provinces and US states, each with a short_name property holding its 2-letter code.
Region map of Canadian provinces and US states shaded by location count, using a custom combined GeoJSON source

A region map built from the combined GeoJSON, colored by location count across US states and Canadian provinces.

Next steps

  • Maps - supported map types and region options.
  • Color by / Stacking - Pin gradient color scale values for consistent intensity coloring.
  • Custom visualizations - Go further with Vega-Lite for map layouts a region map can’t support.
  • Apps - Go even further with custom data experiences backed by live, governed data.