HTTP API & CLI

HTTP API & CLI

The tile server exposes a REST API on port 8070 (configurable via --port).

Endpoints

Method Path Description
GET /tiles/{source}/{z}/{x}/{y}.png Serve a cached tile
GET /sources List all available tile sources
GET /sync/status Current sync job status
POST /sync/start Start a tile sync job
POST /sync/stop Stop the current sync job
GET /health Health check

Serve Tiles

Tiles are served in standard XYZ slippy map format:

GET /tiles/openstreetmap-openstreetmap---standard/12/2038/1365.png

The {source} path segment uses a slugified provider-name format (lowercase, spaces replaced with -, slashes with _).

Start a Sync Job

curl -X POST http://localhost:8070/sync/start \
    -H "Content-Type: application/json" \
    -d '{
        "source": "OpenStreetMap - Standard",
        "bbox": "-0.82,51.25,-0.68,51.32",
        "minZoom": 0,
        "maxZoom": 16
    }'

Check Sync Progress

curl http://localhost:8070/sync/status

Response:

{
    "stateText": "syncing",
    "tilesDownloaded": 450,
    "tilesFromCache": 6,
    "tilesTotal": 808,
    "bytesSynced": 8500000,
    "failedDownloads": 0,
    "tilesPerSecond": 8.4
}

CLI Options

Flag Short Description Default
--port -p HTTP server port 8070
--host -H HTTP bind address 0.0.0.0
--cache-dir -c Tile cache directory ~/.cache/gva-maptiles
--sources -s Path to map sources JSON auto-detected
--concurrent Max concurrent downloads 6
--sync Run a sync job on startup
--source Source name for sync
--bbox Bounding box minLon,minLat,maxLon,maxLat
--zoom Zoom range minZ-maxZ 0-14
--rate-limit Max requests/second (0 = unlimited) 0
--force-refresh Re-download existing tiles
--no-server Sync only, don't start HTTP server

Sync Examples — Farnborough, UK

Farnborough (lat 51.28, lon −0.76) is a common test area. The bounding box -0.82,51.25,-0.68,51.32 covers the town, airfield and surrounding area.

OpenStreetMap

Sync OpenStreetMap tiles for Farnborough at zoom levels 0–16 (~3 400 tiles):

gva-tile-server --sync --no-server \
    --source "OpenStreetMap - Standard" \
    --bbox "-0.82,51.25,-0.68,51.32" \
    --zoom "0-16"

Or trigger the sync via the REST API while the server is running:

curl -X POST http://localhost:8070/sync/start \
    -H "Content-Type: application/json" \
    -d '{
        "source": "OpenStreetMap - Standard",
        "bbox": "-0.82,51.25,-0.68,51.32",
        "minZoom": 0,
        "maxZoom": 16
    }'

Sentinel-2 Satellite Imagery

Sync Sentinel-2 true-colour imagery for Farnborough at zoom levels 0–12. CDSE credentials must be configured first (see Deployment — Copernicus Sentinel-2).

gva-tile-server --sync --no-server \
    --source "Sentinel-2 L2A - True Color" \
    --bbox "-0.82,51.25,-0.68,51.32" \
    --zoom "0-12" \
    --rate-limit 2

Tip

Add --force-refresh to re-download tiles that are already cached, e.g. to pick up newer Sentinel-2 acquisitions.