Available endpoints¶

If you visit the server on the configured port (default 8080) you can see your maps appearing in the browser.

Styles¶

Styles are served at /styles/{id}/style.json (+ array at /styles.json)
- Sprites at /styles/{id}/sprite[/spriteID][@2x].{format}
- Fonts at /fonts/{fontstack}/{start}-{end}.pbf

Rendered tiles¶

Rendered tiles are served at /styles/{id}[/{tileSize}]/{z}/{x}/{y}[@2x].{format}
- The optional ratio @2x (ex. @2x, @3x, @4x) part can be used to render HiDPI (retina) tiles
- The optional tile size /{tileSize} (ex. /256, /512). if omitted, tileSize defaults to 256.
- Available formats: png, jpg (jpeg), webp
- TileJSON at /styles[/{tileSize}]/{id}.json
The rendered tiles are not available in the tileserver-gl-light version.

WMTS Capabilities¶

WMTS Capabilities are served at /styles/{id}/wmts.xml

Static images¶

Several endpoints:
- /styles/{id}/static/{lon},{lat},{zoom}[@{bearing}[,{pitch}]]/{width}x{height}[@2x].{format} (center-based)
- /styles/{id}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}[@2x].{format} (area-based)
- /styles/{id}/static/auto/{width}x{height}[@2x].{format} (autofit path – see below)
All the static image endpoints additionally support following query parameters:
- path - ((fill|stroke|width)\:[^\|]+\|)*(enc:.+|-?\d+(\.\d*)?,-?\d+(\.\d*)?(\|-?\d+(\.\d*)?,-?\d+(\.\d*)?)+)
  - comma-separated lng,lat, pipe-separated pairs
    - e.g. path=5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8
  - Google Encoded Polyline Format
    - e.g. path=enc:_p~iF~ps|U_ulLnnqC_mqNvxq`@
    - If ‘enc:’ is used, the rest of the path parameter is considered to be part of the encoded polyline string – do not specify the coordinate pairs.
  - With options (fill|stroke|width)
    - e.g. path=stroke:yellow|width:2|fill:green|5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8 or path=stroke:blue|width:1|fill:yellow|enc:_p~iF~ps|U_ulLnnqC_mqNvxq`@
  - can be provided multiple times
- latlng - indicates coordinates are in lat,lng order rather than the usual lng,lat for paths and markers
- fill - default color to use as the fill (e.g. red, rgba(255,255,255,0.5), #0000ff) for all paths
- stroke - default color of the path stroke for all paths
- width - default width of the stroke for all paths
- linecap - rendering style for the start and end points of all paths - see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap
- linejoin - rendering style for joining successive segments of all paths when the direction changes - see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
- border - color of the optional border stroke for all paths ; the border is like a halo around the stroke
- borderwidth - width of the border stroke (default 10% of stroke width) for all paths
- marker - Marker in format lng,lat|iconPath|option|option|...
  - Will be rendered with the bottom center at the provided location
  - lng,lat and iconPath are mandatory and icons won’t be rendered without them
  - iconPath is either a link to an image served via http(s) or a path to a file relative to the configured icon path
  - option must adhere to the format optionName:optionValue and supports the following names
    - scale - Factor to scale image by
      - e.g. 0.5 - Scales the image to half it’s original size
    - offset - Image offset as positive or negative pixel value in format [offsetX],[offsetY]
      - scales with scale parameter since image placement is relative to it’s size
      - e.g. 2,-4 - Image will be moved 2 pixel to the right and 4 pixel in the upwards direction from the provided location
  - e.g. 5.9,45.8|marker-icon.png|scale:0.5|offset:2,-4
  - can be provided multiple times
- padding - “percentage” padding for fitted endpoints (area-based and path autofit)
  - value of 0.1 means “add 10% size to each side to make sure the area of interest is nicely visible”
- maxzoom - Maximum zoom level (only for auto endpoint where zoom level is calculated and not provided)
All the static image endpoints support parameters passing using POST with a JSON body:
- e.g. {"path": ["10,10|20,20", "10,20|20,10"]} is the equivalent of ?path=10,10|20,20&path=10,20|20,10
You can also use (experimental) /styles/{id}/static/raw/... endpoints with raw spherical mercator coordinates (EPSG:3857) instead of WGS84.
The static images are not available in the tileserver-gl-light version.

Source data¶

Source data are served at /data/{id}/{z}/{x}/{y}.{format}
- Format depends on the source file (usually png or pbf)
  - geojson is also available (useful for inspecting the tiles) in case the original format is pbf
- TileJSON at /data/{id}.json
- If terrain mbtile data is served and encoding is configured (see config) the elevation can be queried
  - by /data/{id}/elevation/{z}/{x}/{y} for the tile
  - or /data/{id}/elevation/{z}/{long}/{lat} for the coordinate
  - the result will be a json object like {"z":7,"x":68,"y":45,"long":46.04798,"lat":11.84069,"elevation":1602,"pixelX":128,"pixelY":256}
  - for batch requests, POST to /data/{id}/elevation with a JSON body:
    - Request: {"points": [{"lon": 45.5, "lat": 45.5, "z": 1}, ...]}
    - Response: [500, 200, null, ...] - array of elevations (or null if no data) in the same order as input
- The elevation api is not available in the tileserver-gl-light version.

Static files¶

Static files are served at /files/{filename}
- The source folder can be configured (options.paths.files), default is public/files
- This feature can be used to serve geojson files for styles and rendered tiles.
  - Keep in mind, that each rendered tile loads the whole geojson file, if performance matters a conversion to a tiled format (e.g. with https://github.com/felt/tippecanoe)may be a better approch.
  - Use file://{filename} to have matching paths for both endoints

TileJSON arrays¶

Array of all TileJSONs is at [/{tileSize}]/index.json ([/{tileSize}]/rendered.json; /data.json)

The optional tile size /{tileSize} (ex. /256, /512). if omitted, tileSize defaults to 256.

List of available fonts¶

Array of names of the available fonts is at /fonts.json

Health check¶

Endpoint reporting health status is at /health and currently returns:

503 Starting - for a short period before everything is initialized

200 OK - when the server is running