tileserver

Allmaps Tile Server

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:

• https://allmaps.xyz/maps/a38b4ed7ea01a36a/16/33583/21671.png
• https://allmaps.xyz/maps/135dfd2d58dc26ec/6/30/19.png?transformation.type=thin-plate-spline
• https://allmaps.xyz/images/03c17f5180f3a705/16/33572/21876.png
• https://allmaps.xyz/manifests/a0d6d3379cfd9f0a/15/16833/10770.png
• https://allmaps.xyz/manifests/a0d6d3379cfd9f0a/tiles.json
• https://allmaps.xyz/manifests/a0d6d3379cfd9f0a/{z}/{x}/{y}.png
• https://allmaps.xyz/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/images/ea443ffaabb121e2
• https://allmaps.xyz/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/maps/9845523343c39447
• https://allmaps.xyz/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/maps/135dfd2d58dc26ec&transformation.type=thin-plate-spline

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:

• http://localhost:5504/maps/a38b4ed7ea01a36a/16/33583/21671.png
• http://localhost:5504/maps/135dfd2d58dc26ec/6/30/19.png?transformation.type=thin-plate-spline
• http://localhost:5504/images/03c17f5180f3a705/16/33572/21876.png
• http://localhost:5504/manifests/a0d6d3379cfd9f0a/15/16833/10770.png
• http://localhost:5504/manifests/a0d6d3379cfd9f0a/tiles.json
• http://localhost:5504/manifests/a0d6d3379cfd9f0a/{z}/{x}/{y}.png
• http://localhost:5504/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/images/ea443ffaabb121e2
• http://localhost:5504/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/maps/9845523343c39447
• http://localhost:5504/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/maps/135dfd2d58dc26ec&transformation.type=thin-plate-spline

Publish to Cloudflare Workers:

wrangler publish

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:

• https://annotations.allmaps.org/images/ea443ffaabb121e2

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

• https://allmaps.xyz/{z}/{x}/{y}.png?url=https://annotations.allmaps.org/images/ea443ffaabb121e2

Allmaps Tile Server also supports TileJSON:

• https://allmaps.xyz/tiles.json?url=https://annotations.allmaps.org/images/ea443ffaabb121e2

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:

• https://annotations.allmaps.org/?url=https://iiif.nypl.org/iiif/2/58009096

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

• https://api.allmaps.org/images/ea443ffaabb121e2/maps

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

• https://allmaps.xyz/maps/25b0d49e1b659498/{z}/{x}/{y}.png

And for TileJSON:

• https://allmaps.xyz/maps/25b0d49e1b659498/tiles.json

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:

• https://allmaps.xyz/{z}/{x}/{y}.png?annotation=%7B%22type%22%3A%22AnnotationPage…

And for TileJSON:

• https://allmaps.xyz/tiles.json?annotation=%7B%22type%22%3A%22AnnotationPage…

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:

• https://allmaps.xyz/manifests/a0d6d3379cfd9f0a/15/16833/[email protected]
• https://allmaps.xyz/manifests/a0d6d3379cfd9f0a/[email protected]

URL parameters

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