Skip to content
Allmaps Docs

@allmaps/tileserver

Allmaps Tile Server is a proxy server that turns Georeference Annotations into XYZ map tiles.

Allmaps Tile Server runs on Cloudflare Workers. Cloudflare Workers let you run tiny JavaScript programs on Cloudflare’s global CDN. Cloudflare is working on publishing the Workers system as open source.

For more information, see https://observablehq.com/@allmaps/allmaps-tile-server.

Some example URLs:

Development

Run locally with Miniflare:

pnpm run dev

A local version of Allmaps Tile Server is now running on http://localhost:5504.

Some example URLs for local development:

Publish to Cloudflare Workers:

wrangler publish

Deployment (Cloudflare Pages)

This worker uses Cloudflare Pages for automatic deployments, which builds the WASM renderer from Rust source during deployment.

Configure in Cloudflare Dashboard

  1. Go to your Cloudflare Pages project settings
  2. Navigate to Settings → Builds & deployments
  3. Configure the build settings:
Framework preset:        None
Build command:          ./build.sh
Build output directory: dist
Root directory:         workers/tileserver
  1. Set environment variables in Settings → Environment variables:
NODE_VERSION=24
  1. Save and trigger a new deployment

What Happens During Build

The build.sh script automatically:

  • Installs Rust and wasm-pack (cached after first build)
  • Adds wasm32-unknown-unknown target
  • Builds all dependencies including @allmaps/render-wasm
  • Compiles the WASM renderer from Rust source
  • Builds the tileserver worker

Build times:

  • First build: ~3-5 minutes (installs Rust toolchain)
  • Subsequent builds: ~1-2 minutes (Rust is cached)

Local Build Testing

To test the full build process locally:

Terminal window
./build.sh

This mimics what Cloudflare Pages does during deployment.

API

Supplying a Georeference Annotation

To generate XYZ map tiles, Allmaps Tile Server needs a Georeference Annotation. You can supply a Georeference Annotation in three ways:

  1. By using the URL of a Georeference Annotation
  2. By using the Allmaps ID of a georeferenced map
  3. By supplying a complete URL-encoded Georeference Annotation

The different ways of supplying a Georeference Annotation are explained in detail below.

By using the URL of a Georeference Annotation

We can download an example Georeference Annotation of a map of Coney Island from the NYPL from Allmaps API:

You can turn this Georeference Annotation into XYZ tiles like this:

Allmaps Tile Server also supports TileJSON:

Note: Allmaps Tile Server does not depend on https://annotations.allmaps.org. You can use Georeference Annotations from any URL.

By using the Allmaps ID of a georeferenced map

If Allmaps has georeference data available about a certain IIIF resource and you know its Allmaps ID, you can also use this ID directly. If you don’t know its Allmaps ID, you can use https://annotations.allmaps.org to search for the URL of a specific IIIF resource:

You can find out the Allmaps ID of all the maps in a georeferenced image like this:

This image contains one map, with ID 25b0d49e1b659498. The XYZ tile URL of this map is:

And for TileJSON:

By supplying a complete URL-encoded Georeference Annotation

Instead of the URL of a Georeference Annotation, you can also supply the URL-encoded contents of the Georeference Annotation using the annotation URL parameter:

And for TileJSON:

Retina tiles

All PNG and TileJSON URLs are also available in a 512 × 512 pixel retina version. To get retina tiles, add @2x to the end of the URL:

URL parameters

Parameter Description Allowed values Example
transformation.type Transformation type "polynomial" | "thin-plate-spline" ?transformation.type=polynomial