2026-11-19

Auspice v3: New Map Tiles

James HadfieldThe Nextstrain team
Download PDF

Auspice version 3 (September 2026) and v3.1 (October 2026) introduced some major changes to how we render the map. This post will dive into the differences, as well as details for how to update any custom Auspice instances you may be running. Alongside the map changes there were a number of internal changes which you can read about via the release notes: 3.0.0 and 3.1.0.

Auspice v3 is our first major release in almost 7 years, despite over 70 feature releases. This reflects our focus on keeping the interface for consuming projects as stable as possible. The change in map tile provider (described below) necessitated a major version bump as custom Auspice builds which configure the map will need to change.

Vector map tiles via OpenFreeMap

We now use vector map tiles which are rendered in the browser. These have a number of advantages over our previous approach of rasterised tiles. The most noticeable from a user-perspective will be the increased sharpness of the tiles, which is maintained during zooming. Loading times are also marginally improved as the tiles themselves are smaller, and browser caching of tiles is now allowed.

Our map styling has always been heavily customised in order to present a desaturated and unobtrusive looking map where the overlaid (colourful) demes and transmission lines stand out. We previously used (rasterised) tiles from MapBox, where the styling was applied on the MapBox side. The shift to vectorised tiles via OpenFreeMap means the styles are now applied by the browser using our own custom MapLibre Style JSON, which is based on the OpenMapTiles positron theme.

You can compare the differences in Figure 1 by dragging the handle to show the previous tiles (LHS) against the new tiles (RHS). Alternatively, vs ().

Figure 1. Comparison between v2 (LHS) and v3 (RHS) maps when zoomed out Drag the center handle (black arrows) to compare the different versions. The differences in map tiles are almost indistinguishable when zoomed out, although the v3 tiles are noticibly sharper when viewed on a large screen. The map legend (on the far right hand side) is noticibly different as we now show the number of samples (tips) for different circle sizes. The screenshots are taken from our seasonal-flu H3N2 (HA / 2y) dataset, updated 2026-11-12.

When zoomed in the differences are a little more pronounced (Figure 2), as the amount each double-click zooms into the map has changed. The positioning of placenames, and which placenames to show, is also a little different.

Figure 2. Comparison between v2 (LHS) and v3 (RHS) maps when zoomed in Differences become more apparent at higher zoom levels due to each level change zooming in a slightly different amount. Beyond the differences in zoom bounds, the new vector tiles (RHS) are noticeably crisper. The screenshots are taken from our West-African Ebola dataset, updated 2019-12-14.

Legend UI changes

The map legend now shows how many tips different deme (circle) sizes represent (Figure 1, Figure 3).

Hovering on a deme (circle) also shows you the deme name (e.g. which region, country, division) and the number of currently visible tips. If the current coloring is categorical, and thus the deme is rendered as a pie chart, we also show how many tips are behind the currently hovered arc. The previous behavior of highlighting matching tips on the tree (for the entire deme) remains unchanged.

There have also been changes to the rendering of color-by swatches in the legends (Figure 1), including the ability to render as a single column and to allow scrolling within the legend when the number of swatches grows large.

Figure 3. Hovering on a map deme shows tip counts. Screenshot taken using the same dataset as Figure 1, which has a total of 272 H3N2 samples from Japan, of which 43 are classified as clade J.2.

Auspice defaults now work for custom sites

Auspice supports use cases where you want to serve it via your own server instead of nextstrain.org. Previously this required providing your own map customisations as the cost of MapBox tiles meant it wasn't feasible for us to support external servers. The new default settings (OpenMapTiles) don't carry these restrictions and so are usable out-of-the-box for custom Auspice builds.

User customisations are still supported

If you wish to customise the map by providing your own MapLibre style JSON then our customise-client docs have been updated with full details of how to do this, including links to working examples in the Auspice repo.

Map customisations which worked with Auspice v2 will no longer work with Auspice v3, and it was this breaking change which necessitated a major version release. (Other client customisations are unchanged, except for the removal of the already-deprecated Google Analytics support.)

Future directions: offline use

We intend to improve the ability to use Nextstrain tools offline, or with limited internet connections, and the change in tile provider makes this possible.

We recently allowed service workers to allow auspice.us to be accessible without an internet connection by leveraging the browsers cache. We can allow the service worker to serve tiles which exist in the browser cache which would allow offline access for areas of the map you've recently explored. This could be coupled with pre-fetching of tiles from other zoom levels when the user is online.

For local Auspice installs (e.g. nextstrain view or auspice view) we could fetch map tiles from low zoom levels & bundle them with the app so that the app works entirely offline, so long as you don't zoom in too far. The small size of vector tiles makes downloading / bundling the tiles feasible.

All source code is freely available under the terms of the GNU Affero General Public License. Screenshots may be used under a CC-BY-4.0 license and attribution to nextstrain.org must be provided.

This work is made possible by the open sharing of genetic data by research groups from all over the world. We gratefully acknowledge their contributions. Special thanks to Kristian Andersen, Josh Batson, David Blazes, Jesse Bloom, Peter Bogner, Anderson Brito, Matt Cotten, Ana Crisan, Tulio de Oliveira, Gytis Dudas, Vivien Dugan, Karl Erlandson, Nuno Faria, Jennifer Gardy, Nate Grubaugh, Becky Kondor, Dylan George, Ian Goodfellow, Betz Halloran, Christian Happi, Jeff Joy, Paul Kellam, Philippe Lemey, Nick Loman, Duncan MacCannell, Erick Matsen, Sebastian Maurer-Stroh, Placide Mbala, Danny Park, Oliver Pybus, Andrew Rambaut, Colin Russell, Pardis Sabeti, Katherine Siddle, Kristof Theys, Dave Wentworth, Shirlee Wohl and Cecile Viboud for comments, suggestions and data sharing.

Nextstrain is supported by

logologologologologologologo