Using maps in other tools

Use your georeferenced maps in GIS software and other mapping tools. Allmaps provides several ways to do this: load maps as an XYZ tile layer, create GeoTIFF files, render PNG, JPEG, or WebP images, or retrieve map footprints as GeoJSON.

The best option depends on what you want to do and which formats your tool supports. This guide explains when to use each format and how to get started.

XYZ map tiles

XYZ tiles let you display georeferenced maps in GIS software and other tools that support tile layers, such as QGIS. Your tool loads small image tiles as you zoom and pan.

The Allmaps Tile Server creates these tiles on demand. It fetches the original IIIF images from the institutions that host them and warps them using the Georeference Annotations.

To add a map to another tool:

1. Open the map in Allmaps Editor.
2. Open the Export panel and select the maps you want to use.
3. Copy the XYZ map tiles URL.
4. Add this URL as an XYZ tile layer in your tool.

Keep the {z}, {x}, and {y} placeholders in the URL. Your tool replaces them with the zoom level and tile coordinates when requesting tiles.

You can also construct a tile URL from an Allmaps annotation URL: replace annotations.allmaps.org with allmaps.xyz and append /{z}/{x}/{y}.webp. This works for a single map, all maps on an image, or all maps in a IIIF Manifest:

Annotation URL	XYZ tile URL
https://annotations.allmaps.org/maps/135dfd2d58dc26ec	https://allmaps.xyz/maps/135dfd2d58dc26ec/{z}/{x}/{y}.webp
https://annotations.allmaps.org/images/f6033bee94f7763e	https://allmaps.xyz/images/f6033bee94f7763e/{z}/{x}/{y}.webp
https://annotations.allmaps.org/manifests/23379602e8187445	https://allmaps.xyz/manifests/23379602e8187445/{z}/{x}/{y}.webp

Click an XYZ tile URL to preview its maps in the viewer from tiles.allmaps.org. For more URL options, including TileJSON and double-resolution tiles, see the Allmaps Tile Server README.

This lets you use the maps without downloading and processing a complete image first. Loading tiles requires an internet connection and access to the original IIIF images.

About the hosted tile service

Allmaps Tile Server runs on Cloudflare Workers. It fetches IIIF tiles and warps them with our Rust-based WebAssembly renderer, @allmaps/render-wasm. This costs money, currently covered by the OpenHistoricalMap project.

The hosted service is subject to fair use, and we cannot guarantee that it will remain free of charge. The tile server is open source, so you can also host it yourself.

Where possible, we strongly recommend using our Leaflet, MapLibre, or OpenLayers plugins. They warp images in your browser, avoiding the tile server’s rendering costs.

GeoTIFF

Create GeoTIFF files to use your georeferenced maps in GIS software or work with them offline. The example below generates a Bash script using the same @allmaps/io generator as the Allmaps Command Line Interface. The script uses GDAL to warp the images, crop them to their masks, and write Cloud Optimized GeoTIFFs.

Choose an example or paste a Georeference Annotation or Annotation Page URL, then select Generate script. Copy the script or download it as allmaps-geotiff.sh.

Example map Saigon — Bibliothèque nationale de France

Annotation URL

Generate script

Choose a map or enter an annotation URL, then generate its script.

To run the script, install GDAL and jq, and download the original, full-resolution images as JPEGs. Expand Required source images for their filenames and dimensions, and save them in the same directory as the script. The generated script does not download the images for you.

From that directory, run:

bash allmaps-geotiff.sh

You can also install the Allmaps CLI and use allmaps script geotiff to generate the GDAL script from a Georeference Annotation or Annotation Page in your terminal. For usage examples, image-download commands, custom filenames, and more options, see the Allmaps CLI GeoTIFF documentation.

PNG, JPEG, and WebP

Create PNG, JPEG, or WebP images of your georeferenced maps for presentations, publications, or other applications. Allmaps fetches the original IIIF images and warps them directly in your browser. These are ordinary image files; use GeoTIFF when you need embedded georeferencing information.

Choose an example or paste a Georeference Annotation or Annotation Page URL, select a format and image dimensions, then select Render image. All maps in the annotation are fitted into the image without stretching them. Areas outside the maps’ masks are transparent in PNG and WebP images. WebP uses lossless compression. JPEG images use a white background.

Example map Saigon — Bibliothèque nationale de France

Annotation URL

Format PNG

Width (pixels)

Height (pixels)

Render image

Ready to render.

Render a map image

import { Viewport } from '@allmaps/render'
import { WasmRenderer } from '@allmaps/render/wasm'
import initializeWasm, * as wasmModule from '@allmaps/render-wasm'

// Run this code in a Web Worker to keep the page responsive.
await initializeWasm()

const response = await fetch("https://annotations.allmaps.org/maps/1bfb1eb4198e7240@c83337fa4b8051c9")
if (!response.ok) throw new Error('Could not load the annotation')
const annotation = await response.json()

const renderer = new WasmRenderer(wasmModule, {
  outputFormat: 'png'
})

try {
  const results = renderer.addGeoreferenceAnnotation(annotation)
  const failure = results.find((result) => !result.ok)
  if (failure) throw failure.error
  if (!results.length) throw new Error('No georeferenced maps found')

  const viewport = Viewport.fromSizeAndMaps(
    [1024, 1024], renderer.warpedMapList,
    { fit: 'contain' }
  )
  const bytes = await renderer.render(viewport)
  const blob = new Blob([bytes], { type: 'image/png' })
  // Send the image back to the page for preview and download.
  self.postMessage({ blob })
} finally {
  renderer.destroy()
}

Download the result or use the code example to generate an image with @allmaps/render and @allmaps/render-wasm. See the render package README for more rendering options and examples. Rendering happens in your browser, without using the hosted Allmaps Tile Server.

GeoJSON

Use GeoJSON to display map footprints in GIS software or on a web map. Each footprint represents a map’s mask transformed into geographic coordinates. This is useful for showing which areas your maps cover. The GeoJSON contains the footprints and map metadata, but not the map images.

The Allmaps Annotations API can return GeoJSON for a single map, all georeferenced maps on an image, or a search result:

Maps	GeoJSON	Preview
A single map	/maps/135dfd2d58dc26ec.geojson	View in geojson.io
Maps on an image	/images/f6033bee94f7763e.geojson	View in geojson.io
Maps covering a location	/maps.geojson?intersects=52.01,4.36&limit=10	View in geojson.io

A single map returns a GeoJSON Feature; multiple maps return a FeatureCollection. Download the GeoJSON or load its URL directly into a tool that supports it. Select View in geojson.io to explore the footprints on an interactive map.

See the Annotations API documentation for available filters and query parameters.

To add georeferenced maps to your own website with Leaflet, MapLibre, or OpenLayers, see Viewing maps.