Protomaps

https://docs.protomaps.com/
Admin
Protomaps is an open source mapping system providing PMTiles archive format, tools for creating and...
Tokens:32,304
Snippets:285
Trust Score:8.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install protomaps-leaflet with npm

Source: https://docs.protomaps.com/basemaps/leaflet

Installs the protomaps-leaflet package for use with a bundler.

```bash
npm add protomaps-leaflet
```

--------------------------------

### Install pmtiles library

Source: https://docs.protomaps.com/pmtiles/maplibre

Install the pmtiles JavaScript library, required for reading PMTiles directly from cloud storage in MapLibre GL.

```bash
npm install pmtiles
```

--------------------------------

### Install ol-pmtiles with npm

Source: https://docs.protomaps.com/pmtiles/openlayers

Install the ol-pmtiles package to use PMTiles with OpenLayers.

```bash
npm install ol-pmtiles
```

--------------------------------

### Serve PMTiles locally with http-server

Source: https://docs.protomaps.com/pmtiles

Install the npm package http-server globally, then serve the directory containing your .pmtiles file with CORS enabled. The file becomes available at http://localhost:8080/.

```sh
npm install -g http-server
# from the directory containing your .pmtiles file
http-server . --cors
# your file is now available at http://localhost:8080/
```

--------------------------------

### Install @protomaps/basemaps npm package

Source: https://docs.protomaps.com/basemaps/maplibre

Installs the @protomaps/basemaps package as a dependency for programmatically creating MapLibre styles.

```bash
npm install @protomaps/basemaps
```

--------------------------------

### List of sprite names from light.json

Source: https://docs.protomaps.com/basemaps/flavors

Sprite names can be found in light.json. This example shows a partial list of sprite names that can be replaced with custom sets.

```CSV
townspot
capital
arrow
generic_shield-1char
...
```

--------------------------------

### Convert GeoTIFF to PMTiles with rio-pmtiles

Source: https://docs.protomaps.com/pmtiles/create

Converts a GeoTIFF to PMTiles using the rio-pmtiles plugin for Rasterio. First expands a single-band GeoTIFF to RGB, installs rio-pmtiles, then runs the conversion. Options include --format (PNG, JPEG, WEBP; default WEBP), --tile-size (default 512), --resampling (default bilinear), --silent, --zoom-levels, and --help.

```sh
# convert single-band to 3-band RGB GeoTIFF
gdal_translate -expand rgb input.tif input_rgb.tif

pip install rio-pmtiles

rio pmtiles input_rgb.tif output.pmtiles --format PNG --resampling bilinear
```

--------------------------------

### Build the planet with protomaps-basemap

Source: https://docs.protomaps.com/basemaps/build

Build a planet-wide tileset using a Planet file from planet.openstreetmap.org. The -Xmx20g flag gives the JVM 20GB of heap, --nodemap-type=array is optimized for planet generation, and --tmpdir must have at least 512GB of scratch space.

```sh
java -Xmx20g -jar target/protomaps-basemap-HEAD-with-deps.jar --nodemap-type=array --osm_path=/data/planet-latest.osm.pbf --output=/data/planet.pmtiles --bounds=planet --tmpdir=/var/scratch
```

--------------------------------

### Build a local map with protomaps-basemap

Source: https://docs.protomaps.com/basemaps/build

First, clone the basemaps repository and build the JAR with Maven. Then, place your OSM extract in data/sources and run the tile generation JAR with the --clip and --area arguments; the --download flag fetches additional resources like water polygons and language data.

```sh
git clone https://github.com/protomaps/basemaps
cd basemaps/tiles
mvn clean package
```

```sh
cp my_area.osm.pbf data/sources/my_area.osm.pbf
java -jar target/protomaps-basemap-HEAD-with-deps.jar --clip=lodz.geojson --area=my_area --download
```

--------------------------------

### Minimal Caddyfile for serving a PMTiles bucket

Source: https://docs.protomaps.com/deploy/server

This Caddyfile configuration serves a bucket of PMTiles archives. The handle_path directive strips the /tiles prefix, and the order directive is required. The bucket URL can be any gocloud-compatible URL, cache_size sets the cache in MB, and public_url is needed only for TileJSON responses.

```txt
{
  order pmtiles_proxy before reverse_proxy
}

localhost:2019 {
  handle_path /tiles/* {
    pmtiles_proxy {
      bucket https://example.com
      cache_size 256
      public_url https://localhost:2019/tiles
    }
  }
}

```

--------------------------------

### Amazon S3 CORS Configuration

Source: https://docs.protomaps.com/pmtiles/cloud-storage

CORS configuration for Amazon S3, allowing GET and HEAD requests with range and if-match headers.

```json
[
    {
      "AllowedOrigins": ["https://example.com"],
      "AllowedMethods": ["GET","HEAD"],
      "AllowedHeaders": ["range","if-match"],
      "ExposeHeaders": ["etag"],
      "MaxAgeSeconds": 3000
    }
]
```

--------------------------------

### Cloudflare R2 CORS Configuration JSON

Source: https://docs.protomaps.com/pmtiles/cloud-storage

JSON structure for setting CORS on Cloudflare R2, allowing GET and HEAD requests with range and if-match headers.

```json
{
    "allowed": {
        "origins": ["https://example.com"],
        "methods": ["GET","HEAD"],
        "headers": ["range","if-match"],
    },
    "exposeHeaders": ["etag"],
    "maxAgeSeconds": 3000
}
```

--------------------------------

### pmtiles serve command

Source: https://docs.protomaps.com/pmtiles/cli

Serve a directory or bucket of tilesets as a ZXY endpoint. Raw file requests are not supported; use a standard web server for those.

```bash
pmtiles serve .
```

--------------------------------

### Google Cloud CORS Configuration JSON

Source: https://docs.protomaps.com/pmtiles/cloud-storage

JSON structure for setting CORS on Google Cloud Storage, allowing GET and HEAD requests with range, etag, and if-match headers.

```json
[
    {
      "origin": ["https://example.com"],
      "method": ["GET","HEAD"],
      "responseHeader": ["range","etag","if-match"],
      "maxAgeSeconds": 300
    }
]
```

--------------------------------

### Include protomaps-leaflet via script tag

Source: https://docs.protomaps.com/basemaps/leaflet

Loads the protomaps-leaflet library from unpkg and initializes a Leaflet map with a protomaps layer. The url must be a .pmtiles file or an endpoint template. The flavor option must be one of light, dark, white, grayscale, or black; lang can be a supported language.

```html
<script src="https://unpkg.com/protomaps-leaflet@5.0.0/dist/protomaps-leaflet.js"></script>
<script>
    const map = L.map('map')
    var layer = protomapsL.leafletLayer({url:'FILE.pmtiles OR ENDPOINT/{z}/{x}/{y}.mvt', flavor: 'light', lang: 'en'})
    layer.addTo(map)
</script>
```

--------------------------------

### AWS IAM policy for S3 write access

Source: https://docs.protomaps.com/pmtiles/cli

Example IAM policy granting full S3 permissions on a bucket. Required for the pmtiles upload command to write to the bucket.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::my-bucket-name/*"
        }
    ]
}
```

--------------------------------

### Verify pmtiles_proxy plugin with caddy list-modules

Source: https://docs.protomaps.com/deploy/server

Run this command to confirm the pmtiles_proxy plugin is included in your Caddy build. The expected output shows the plugin listed under http.handlers.pmtiles_proxy.

```sh
caddy list-modules
...
http.handlers.pmtiles_proxy

  Non-standard modules: 1

```

--------------------------------

### Serve PMTiles archives with pmtiles serve

Source: https://docs.protomaps.com/pmtiles/cli

Serves the current directory, root, or a prefix at http://localhost:8080/TILESET/{z}/{x}/{y}.mvt with TileJSON at http://localhost:8080/TILESET.json. The .pmtiles extension is added automatically. For ZXY URLs, the extension must match the tile type (e.g., mvt, png, jpg, webp, avif).

```bash
pmtiles serve . --bucket=https://example.com
```

```bash
pmtiles serve / --bucket=s3://BUCKET_NAME
```

```bash
pmtiles serve PREFIX --bucket=s3://BUCKET_NAME
```

--------------------------------

### Upload PMTiles to S3

Source: https://docs.protomaps.com/pmtiles/cli

Uploads a PMTiles archive to an S3 bucket. Requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. The second example shows how to use a custom S3-compatible endpoint with path-style requests.

```bash
# requires environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY credentials
pmtiles upload INPUT.pmtiles REMOTE.pmtiles --bucket=s3://BUCKET_NAME
```

```bash
# upload to a s3-compatible endpoint
# some storage systems require path-style requests
pmtiles upload INPUT.pmtiles REMOTE.pmtiles --bucket=s3://BUCKET_NAME?region=auto&endpoint=https://example.com&use_path_style=true
```

--------------------------------

### Set S3 credentials in Caddy unit file

Source: https://docs.protomaps.com/deploy/server

Add these environment variables to Caddy's systemd unit file to provide S3 credentials for the gocloud library. Replace the placeholder values with your actual keys.

```txt
...
[Service]
Environment=AWS_ACCESS_KEY_ID=mykey
Environment=AWS_SECRET_ACCESS_KEY=mysecret
...

```

--------------------------------

### Override default flavor with ES6 spread syntax

Source: https://docs.protomaps.com/basemaps/flavors

Use ES6 spread syntax to override any part of the Flavor object. This example colors buildings red by spreading the 'light' flavor and setting the 'buildings' property.

```TypeScript
import { namedFlavor } from "@protomaps/basemaps"
let flavor = {...namedFlavor("light"),buildings:"red"}
```

--------------------------------

### Register pmtiles protocol with MapLibre GL

Source: https://docs.protomaps.com/pmtiles/maplibre

Create a Protocol instance and register it with MapLibre GL using addProtocol. This enables the pmtiles:// protocol for sources.

```js
let protocol = new Protocol();
maplibregl.addProtocol("pmtiles",protocol.tile);
```

--------------------------------

### Content Security Policy meta tag for MapLibre

Source: https://docs.protomaps.com/guide/security-privacy

An example HTML CSP policy that includes MapLibre's required directives. It sets default-src to 'self' with nonces, allows blob: for workers and child sources, and allows data: and blob: for images.

```html
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self' 'nonce-n0nce' 'nonce-n0nce1'; worker-src blob: ; child-src blob: ; img-src data: blob: ;" />
```

--------------------------------

### Convert MBTiles to PMTiles using Docker

Source: https://docs.protomaps.com/pmtiles/cli

Runs pmtiles convert inside the Docker image protomaps/go-pmtiles, mounting the current directory to /data. Converts /data/INPUT.mbtiles to /data/OUTPUT.pmtiles.

```sh
docker run -v $(pwd):/data --rm protomaps/go-pmtiles convert /data/INPUT.mbtiles /data/OUTPUT.pmtiles
```

--------------------------------

### Print pmtiles version

Source: https://docs.protomaps.com/pmtiles/cli

Prints the version of the pmtiles command line tool.

```bash
pmtiles version
```

--------------------------------

### pmtiles extract command variants

Source: https://docs.protomaps.com/pmtiles/cli

Create a smaller archive from a larger archive. Source may be local or remote and must be clustered. Options include --maxzoom, --minzoom, --region, --download-threads, --overfetch.

```bash
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --region=REGION.geojson
pmtiles extract https://example.com/INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM --bucket=s3://BUCKET_NAME
```

--------------------------------

### Azure Container App Command Override for go-pmtiles

Source: https://docs.protomaps.com/deploy/azure

Command override for the Azure Container App. Substitute main with your Blob Storage container name, account with your Storage Account name, and https://example.com with the final user-facing URL. Leaving the public URL blank will break TileJSON.

```text
/go-pmtiles, serve, ., --bucket=azblob://main?storage_account=account, --public-url=https://example.com
```

--------------------------------

### Build default spritesheets with cargo and make

Source: https://docs.protomaps.com/basemaps/flavors

Commands to build the spritegen binary and generate all five default flavor spritesheets. The final command shows how to generate a custom spritesheet from a custom JSON configuration.

```Shell
cargo build # creates the binary target/release/spritegen
make # builds all 5 default flavor spritesheets in dist/
# Create a new JSON in flavors/custom.json and customize the colors...
./target/release/spritegen refill.svg flavors/custom.json dist/custom
```

--------------------------------

### pmtiles verify command

Source: https://docs.protomaps.com/pmtiles/cli

Check that an archive is ordered correctly and has correct header information.

```bash
pmtiles verify INPUT.pmtiles
```

--------------------------------

### pmtiles show command variants

Source: https://docs.protomaps.com/pmtiles/cli

Print an archive's header data and metadata. Options: --header-json prints a JSON representation of part of the header, --metadata prints the JSON metadata.

```bash
pmtiles show INPUT.pmtiles
pmtiles show INPUT.pmtiles --bucket=s3://BUCKET_NAME
pmtiles show INPUT.pmtiles --header-json
pmtiles show INPUT.pmtiles --metadata
```

--------------------------------

### pmtiles serve

Source: https://docs.protomaps.com/pmtiles/cli

Serves a directory or bucket of tilesets (like TILESET.pmtiles) from local or cloud storage as a ZXY endpoint. Using `pmtiles serve` also allows serving a public API from a private storage bucket.

```APIDOC
## pmtiles serve

### Description
Serves a directory or bucket of tilesets (like TILESET.pmtiles) from local or cloud storage as a ZXY endpoint. Using `pmtiles serve` also allows serving a public API from a private storage bucket.

### Usage
```bash
pmtiles serve .
```

### Parameters
- `DIRECTORY` (string) - Required - Directory or bucket to serve.
```

--------------------------------

### Show local archive

Source: https://docs.protomaps.com/pmtiles/cli

Display header and metadata for a local PMTiles archive.

```sh
pmtiles show test.pmtiles
```

--------------------------------

### Import Protocol from pmtiles

Source: https://docs.protomaps.com/pmtiles/maplibre

Import the Protocol class from the pmtiles library to enable the MapLibre GL plugin.

```js
import { Protocol } from "pmtiles";
```

--------------------------------

### Load @protomaps/basemaps from CDN

Source: https://docs.protomaps.com/basemaps/maplibre

Loads the @protomaps/basemaps package from a CDN, defining the basemaps global variable.

```html
<script src="https://unpkg.com/@protomaps/basemaps@5/dist/basemaps.js" crossorigin="anonymous"></script>
```

--------------------------------

### Upload PMTiles to Source Cooperative with pmtiles CLI

Source: https://docs.protomaps.com/pmtiles/cloud-storage

Uploads a PMTiles file to Source Cooperative using the pmtiles CLI. Requires an API key, Access Key ID, and Secret Access Key from the Manage page. Uses the S3-compatible endpoint with path style.

```sh
export AWS_ACCESS_KEY_ID=YOUR_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET
pmtiles upload file.pmtiles path/in/bucket/key.pmtiles --bucket=s3://ORGANIZATION_NAME?endpoint=https://data.source.coop&region=auto&use_path_style=true
```

--------------------------------

### Edit PMTiles header and metadata

Source: https://docs.protomaps.com/pmtiles/cli

Shows how to export the current header and metadata to JSON files, edit them, and then apply the changes. Editing only the header modifies the file in-place; writing metadata requires a new copy of the archive.

```bash
pmtiles show NAME.pmtiles --header-json > header.json
pmtiles show NAME.pmtiles --metadata > metadata.json

# make changes to header.json or metadata.json

pmtiles edit NAME.pmtiles --header-json=header.json --metadata=metadata.json
```

--------------------------------

### Generate custom spritesheet with spreet

Source: https://docs.protomaps.com/basemaps/flavors

Use the spreet command line tool to generate a spritesheet with a single icon based on the CC0 Maki icon set. The commands create output.json and output.png, and with --retina create output@2x.json and output@2x.png for HiDPI displays.

```Shell
mv airport.svg icons/aerodrome.svg
spreet icons output
# creates output.json and output.png
spreet --retina icons output@2x
#creates output@2x.json and output@2x.png, used on HiDPI displays
```

--------------------------------

### Upload PMTiles with RClone

Source: https://docs.protomaps.com/pmtiles/cloud-storage

Use RClone to copy a PMTiles file to S3-compatible storage with progress and chunk size options.

```sh
rclone copyto my-filename my-configuration:my-bucket/my-folder/my-filename.pmtiles --progress --s3-chunk-size=256M
```

--------------------------------

### Create MapLibre style with @protomaps/basemaps

Source: https://docs.protomaps.com/basemaps/maplibre

Defines a MapLibre style object using the @protomaps/basemaps layers function. The source URL must be prefixed with pmtiles://. The layers function takes the source name, a flavor object (e.g., namedFlavor("light")), and an options object with lang for labels.

```javascript
style: {
    version: 8,
    glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf',
    sprite: "https://protomaps.github.io/basemaps-assets/sprites/v4/light",
    sources: {
        "protomaps": {
            type: "vector",
            url: "pmtiles://https://example.com/example.pmtiles",
            //       ^-- Remember to prefix the URL with pmtiles://
            attribution: '<a href="https://protomaps.com">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>'
        }
    },
    layers: layers("protomaps",namedFlavor("light"),{lang:"en"})
}
```

--------------------------------

### Inspect a PMTiles archive with pmtiles show

Source: https://docs.protomaps.com/guide/getting-started

Inspect a daily basemap archive with the pmtiles CLI. The output shows the planetiler:osm:osmosisreplicationtime metadata, confirming the OpenStreetMap data date.

```bash
pmtiles show https://build.protomaps.com/20261002.pmtiles
```

```txt
...
planetiler:osm:osmosisreplicationtime 2026-10-02T05:00:00Z
...
```

--------------------------------

### pmtiles show

Source: https://docs.protomaps.com/pmtiles/cli

Prints an archive's header data and metadata.

```APIDOC
## pmtiles show

### Description
Prints an archive's header data and metadata.

### Usage
```bash
pmtiles show INPUT.pmtiles
pmtiles show INPUT.pmtiles --bucket=s3://BUCKET_NAME
pmtiles show INPUT.pmtiles --header-json
pmtiles show INPUT.pmtiles --metadata
```

### Parameters
- `INPUT.pmtiles` (string) - Required - Path or URL to the PMTiles archive.
- `--bucket` (string) - Optional - Cloud storage bucket URI (e.g., `s3://BUCKET_NAME`, `azblob://CONTAINER_NAME?storage_account=ACCOUNT`, `gs://BUCKET_NAME`).
- `--header-json` (flag) - Optional - Print a JSON representation of part of the header to stdout.
- `--metadata` (flag) - Optional - Print the JSON metadata to stdout.
```

--------------------------------

### pmtiles extract

Source: https://docs.protomaps.com/pmtiles/cli

Creates a smaller archive from a larger archive. The source archive may be local or remote. The source archive must be clustered.

```APIDOC
## pmtiles extract

### Description
Creates a smaller archive from a larger archive. The source archive may be local or remote. The source archive must be clustered.

### Usage
```bash
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --region=REGION.geojson
pmtiles extract https://example.com/INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM --bucket=s3://BUCKET_NAME
```

### Parameters
- `INPUT.pmtiles` (string) - Required - Path or URL to the source archive.
- `OUTPUT.pmtiles` (string) - Required - Path to the output archive.
- `--bbox` (string) - Optional - Bounding box as `MIN_LON,MIN_LAT,MAX_LON,MAX_LAT`.
- `--region` (string) - Optional - Path to a GeoJSON Polygon, Multipolygon, Feature, or FeatureCollection.
- `--maxzoom` (integer) - Optional - Extract only a subset of zoom levels. Extracting a full sub-pyramid from 0 to `maxzoom` is always an efficient operation that makes minimal I/O or network requests to the source archive.
- `--minzoom` (integer) - Optional - Extract only a partial sub-pyramid. This may require many more requests than leaving the default `--minzoom=0`. Because this removes overview zoom levels, it should only be used in specific situations.
- `--download-threads` (integer) - Optional - Number of parallel requests to speed up downloads.
- `--overfetch` (float) - Optional - Extra data to download to batch small requests: 0.05 is 5%.
```
Tokens:
Raw