Api

API Endpoints

REST API reference for Tileserver RS

Tileserver RS provides a REST API for accessing tiles and metadata.

Health Check

GET /health

Returns OK if the server is running.

Response: 200 OK

All endpoints that return URLs support an optional ?key query parameter. When provided, the key is appended to all URLs in the response, enabling API gateway/proxy scenarios where authentication needs to be forwarded through subsequent requests.

Example:

GET /styles/osm-bright/style.json?key=my_api_key

All URLs in the response will include ?key=my_api_key:

{
  "sources": {
    "openmaptiles": {
      "url": "http://localhost:8080/data/openmaptiles.json?key=my_api_key"
    }
  },
  "glyphs": "http://localhost:8080/fonts/{fontstack}/{range}.pbf?key=my_api_key",
  "sprite": "http://localhost:8080/styles/osm-bright/sprite?key=my_api_key"
}

Supported endpoints:

/data.json
/data/{source}.json
/index.json
/styles.json
/styles/{style}.json
/styles/{style}/style.json
/styles/{style}/wmts.xml

List All Sources

GET /data.json

Returns a list of all available tile sources with their TileJSON metadata.

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to all tile URLs

Response:

[
  {
    "tilejson": "3.0.0",
    "name": "OpenMapTiles",
    "tiles": ["http://localhost:8080/data/openmaptiles/{z}/{x}/{y}.pbf"],
    "minzoom": 0,
    "maxzoom": 14,
    "bounds": [-180, -85.0511, 180, 85.0511],
    "center": [0, 0, 2]
  }
]

Get Source TileJSON

GET /data/{source}.json

Returns TileJSON metadata for a specific source.

Parameters:

Name	Type	Description
`source`	string	Source ID

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to tile URLs

Response:

{
  "tilejson": "3.0.0",
  "name": "OpenMapTiles",
  "tiles": ["http://localhost:8080/data/openmaptiles/{z}/{x}/{y}.pbf"],
  "vector_layers": [...],
  "minzoom": 0,
  "maxzoom": 14,
  "bounds": [-180, -85.0511, 180, 85.0511],
  "center": [0, 0, 2]
}

Get Tile

GET /data/{source}/{z}/{x}/{y}.{format}

Returns a single tile from a source. Works with all source types (PMTiles, MBTiles, PostgreSQL).

Parameters:

Name	Type	Description
`source`	string	Source ID (from config)
`z`	integer	Zoom level (0-22)
`x`	integer	Tile X coordinate
`y`	integer	Tile Y coordinate
`format`	string	Tile format (`pbf`, `png`, `jpg`, `webp`)

Examples:

# PMTiles source
GET /data/openmaptiles/14/8192/5461.pbf

# MBTiles source
GET /data/terrain/10/512/340.pbf

# PostgreSQL table source
GET /data/buildings/12/2048/1365.pbf

# PostgreSQL function source
GET /data/custom_tiles/14/8580/5737.pbf

Response Headers:

Header	Description
`Content-Type`	MIME type based on format
`Content-Encoding`	`gzip` if tile is compressed
`Cache-Control`	Caching headers

Response Codes:

Code	Description
`200`	Tile found and returned
`204`	Tile not found (empty response)
`400`	Invalid coordinates
`404`	Source not found

List Styles

GET /styles.json

Returns a list of all available map styles.

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to style URLs

Response:

[
  {
    "id": "protomaps-light",
    "name": "Protomaps Light",
    "url": "http://localhost:8080/styles/protomaps-light/style.json"
  }
]

Get Style JSON

GET /styles/{style}/style.json

Returns the MapLibre/Mapbox GL style JSON for vector rendering.

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to all URLs (sources, glyphs, sprites)

Get Raster TileJSON

GET /styles/{style}.json

Returns TileJSON metadata for raster tile rendering of a style.

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to raster tile URLs

Response:

{
  "tilejson": "3.0.0",
  "name": "Protomaps Light",
  "tiles": ["http://localhost:8080/styles/protomaps-light/{z}/{x}/{y}.png"],
  "minzoom": 0,
  "maxzoom": 22
}

Get Raster Tile

GET /styles/{style}/{z}/{x}/{y}[@{scale}x].{format}

Returns a rendered raster tile from a vector style.

Parameters:

Name	Type	Description
`style`	string	Style ID
`z`	integer	Zoom level (0-22)
`x`	integer	Tile X coordinate
`y`	integer	Tile Y coordinate
`scale`	integer	Optional scale factor (1-3, default: 1)
`format`	string	Output format (`png`, `jpeg`, `webp`)

Examples:

/styles/protomaps-light/14/8192/5461.png          # 512x512 PNG @ 1x
/styles/protomaps-light/14/8192/5461@2x.png       # 1024x1024 PNG @ 2x (retina)
/styles/protomaps-light/14/8192/5461.webp         # 512x512 WebP

Performance:

Warm cache: ~100ms per tile
Cold cache: ~700-800ms (includes tile fetching)

Get Static Map Image

GET /styles/{style}/static/{type}/{width}x{height}[@{scale}x].{format}

Returns a static map image centered on a location or bounding box.

Static Image Types:

Center: {lon},{lat},{zoom}[@{bearing}[,{pitch}]]
Bounding Box: {minx},{miny},{maxx},{maxy}
Auto-fit: auto (requires ?path= or ?marker= query params)

Query Parameters:

Name	Description
`path`	Path/polyline overlay (see format below)
`marker`	Marker overlay (see format below)
`padding`	Padding ratio for auto-fit (default: 0.1)
`maxzoom`	Maximum zoom level for auto-fit

Examples:

# Center-based
/styles/protomaps-light/static/-122.4,37.8,12/800x600.png
/styles/protomaps-light/static/-122.4,37.8,12@45,60/800x600@2x.webp

# Bounding box
/styles/protomaps-light/static/-123,37,-122,38/1024x768.jpeg

# Auto-fit with path
/styles/protomaps-light/static/auto/800x600.png?path=path-5+f00(-122.4,37.8|-122.5,37.9|-122.4,38.0)

# With markers
/styles/protomaps-light/static/-122.4,37.8,12/800x600.png?marker=pin-s+f00(-122.4,37.8)

Path Format

Paths are specified as: path-{strokeWidth}+{strokeColor}({coordinates})

strokeWidth: Line width in pixels (default: 3)
strokeColor: Hex color (3 or 6 digits, e.g., f00 or ff0000)
coordinates: Pipe-separated lon,lat pairs

Multiple paths can be separated by ~.

Example:

path-5+ff0000(-122.4,37.8|-122.5,37.9|-122.4,38.0)

Marker Format

Markers are specified as: pin-{size}-{label}+{color}({lon},{lat})

size: s (small), m (medium), or l (large)
label: Optional single character label
color: Hex color

Multiple markers can be separated by ~.

Example:

pin-s+f00(-122.4,37.8)~pin-m-A+00f(-122.5,37.9)

Get Sprite

GET /styles/{style}/sprite[@{scale}x].{format}

Returns sprite image or metadata for a style.

Parameters:

Name	Type	Description
`style`	string	Style ID
`scale`	integer	Optional scale factor (2x, 3x for retina)
`format`	string	`png` for image, `json` for metadata

Examples:

/styles/protomaps-light/sprite.json       # Sprite metadata
/styles/protomaps-light/sprite.png        # Sprite image (1x)
/styles/protomaps-light/sprite@2x.json    # Retina metadata
/styles/protomaps-light/sprite@2x.png     # Retina image (2x)

Get WMTS Capabilities

GET /styles/{style}/wmts.xml

Returns OGC WMTS 1.0.0 GetCapabilities document for use with GIS software (QGIS, ArcGIS).

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to all tile URLs in the capabilities document

Font Endpoints

List Fonts

GET /fonts.json

Returns a list of all available font families.

Response:

["Noto Sans Regular", "Noto Sans Medium", "Open Sans Bold"]

Get Font Glyphs

GET /fonts/{fontstack}/{range}.pbf

Returns font glyphs in PBF format for text rendering.

Parameters:

Name	Type	Description
`fontstack`	string	Font name or comma-separated fallback stack
`range`	string	Character range (e.g., `0-255`, `256-511`)

Examples:

/fonts/Noto Sans Regular/0-255.pbf
/fonts/Noto Sans Bold,Arial Unicode MS Regular/256-511.pbf

Font Stack Fallback:

When a font stack is requested (comma-separated), the server tries each font in order and returns the first available match. This enables fallback behavior for missing glyphs.

Other Endpoints

Combined Index

GET /index.json

Returns a combined array of all TileJSONs (both data sources and raster styles).

Query Parameters:

Name	Type	Description
`key`	string	Optional API key to append to all tile URLs

Response:

[
  {
    "tilejson": "3.0.0",
    "id": "openmaptiles",
    "name": "OpenMapTiles",
    "tiles": ["http://localhost:8080/data/openmaptiles/{z}/{x}/{y}.pbf"],
    ...
  },
  {
    "tilejson": "3.0.0",
    "name": "Protomaps Light",
    "tiles": ["http://localhost:8080/styles/protomaps-light/{z}/{x}/{y}.png"],
    ...
  }
]

Get Tile as GeoJSON

GET /data/{source}/{z}/{x}/{y}.geojson

Returns a vector tile converted to GeoJSON format. Useful for debugging and inspection.

Parameters:

Name	Type	Description
`source`	string	Source ID (must be a vector tile source)
`z`	integer	Zoom level
`x`	integer	Tile X coordinate
`y`	integer	Tile Y coordinate

Response:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Example",
        "_layer": "places"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [1205, 1540]
      }
    }
  ]
}

GeoJSON coordinates are in tile coordinate space (0-4096), not geographic coordinates. This endpoint is primarily for debugging tile contents.

Get Static File

GET /files/{filepath}

Serves static files from the configured files directory. Useful for serving GeoJSON overlays, custom icons, or other static assets.

Parameters:

Name	Type	Description
`filepath`	string	Path to the file relative to the files directory

Examples:

/files/data.geojson
/files/icons/marker.png
/files/overlays/route.json

Security:

Path traversal (..) is blocked
Only files within the configured directory are accessible

Response Headers:

Content-Type: Determined by file extension
Cache-Control: public, max-age=3600

Edit this pageorReport an issue

Performance Benchmarks

Benchmark results comparing PMTiles, MBTiles, PostgreSQL, and COG (raster) performance in tileserver-rs

Static Map Images

Generate static map images for thumbnails, social cards, and print