API Endpoints

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

Ping (Runtime Metadata)

GET /ping

Returns runtime metadata about the running server instance. Useful for monitoring, debugging, and verifying configuration state.

Response:

{
  "status": "ok",
  "config_hash": "a1b2c3d4e5f6...",
  "loaded_at_unix": 1708444800,
  "loaded_sources": 3,
  "loaded_styles": 2,
  "renderer_enabled": true,
  "version": "2.8.1"
}

Field	Type	Description
`status`	string	Always `"ok"`
`config_hash`	string	SHA-256 hash of the current configuration
`loaded_at_unix`	integer	Unix timestamp when config was last loaded
`loaded_sources`	integer	Number of tile sources currently loaded
`loaded_styles`	integer	Number of styles currently loaded
`renderer_enabled`	boolean	Whether native MapLibre rendering is available
`version`	string	Server version from `Cargo.toml`

Hot Reload (Admin)

POST /__admin/reload

Reloads the server configuration without downtime. Only available on the admin server (configured via admin_bind in [server]).

Query Parameters:

Name	Type	Description
`flush`	boolean	Force reload even if config hash is unchanged (default: `false`)

Response (success):

{
  "ok": true,
  "reloaded": true,
  "config_hash": "f6e5d4c3b2a1...",
  "loaded_at_unix": 1708444900,
  "loaded_sources": 4,
  "loaded_styles": 2,
  "renderer_enabled": true,
  "version": "2.8.1"
}

When reloaded is false, the config hash hasn't changed and no reload was performed (use ?flush=true to force).

Response (error):

{
  "ok": false,
  "error": "Failed to parse config: expected `=`, found `[` at line 5"
}

Warning

On error, the server keeps the previous working configuration. No data is lost.

Info

You can also reload by sending SIGHUP to the server process: kill -HUP <pid>. See the Hot Reload Guide for details.

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]
}

Info

For sources using MapLibre Tiles (MLT) format, the TileJSON response includes an "encoding": "mlt" field and tile URLs use the .mlt extension.

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`, `mlt`, `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 (`application/x-protobuf` for PBF, `application/vnd.maplibre-vector-tile` for MLT)
`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]
      }
    }
  ]
}

Warning

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