Provider

Proxy

The Proxy provider is the simplest option that simply forwards tile requests to another HTTP(s) endpoint. This provider can be used for mapping services that operate in tiles (ZXY, TMS, or WMTS) or against bounds (i.e. WMS). TMS inverts the y coordinate compared to ZXY and WMTS formats, which is handled by the InvertY parameter.

ZXY · TMS · WMTS · WMS

Example

YAML
JSON

provider:
  name: proxy
  url: https://tile.openstreetmap.org/{z}/{x}/{y}.png?key={env.key}&agent={ctx.User-Agent}

{
  "provider": {
    "name": "proxy",
    "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png?key={env.key}&agent={ctx.User-Agent}"
  }
}

Configuration

Configuration options
Parameter	Description	Type	Required	Default
`url`	A URL pointing to the tile server. Should contain placeholders surrounded by "{}" that are replaced on-the-fly	string	Yes	None
`inverty`	Changes Y tile numbering to be South-to-North instead of North-to-South. Only impacts Y/y placeholder	bool	No	false
`srid`	What projection bounds should be in. Can only be 4326 or 3857	uint	No	4326

URL placeholders

Placeholder Description

Placeholder	Description
`x, X`	The X tile coordinate from the incoming request
`y, Y`	The Y tile coordinate either from the incoming request or the "flipped" equivalent if the `invertY` parameter is specified.
`z, Z`	The Z tile coordinate from the incoming request (aka "zoom")
`xmin`	The "west" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by `srid`.
`xmax`	The "east" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by `srid`.
`ymin`	The "south" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by `srid`. Not impacted by the `invertY` parameter.
`ymax`	The "north" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by `srid`. Not impacted by the `invertY` parameter.
`env.XXX`	An environment variable whose name is XXX
`ctx.XXX`	A context variable (typically an HTTP header) whose name is XXX
`layer.XXX`	If the layer includes a pattern with a placeholder of XXX, this is the replacement value from the used layer name

x, X

The X tile coordinate from the incoming request

y, Y

The Y tile coordinate either from the incoming request or the "flipped" equivalent if the invertY parameter is specified.

z, Z

The Z tile coordinate from the incoming request (aka "zoom")

xmin

The "west" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by srid.

xmax

The "east" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by srid.

ymin

The "south" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by srid. Not impacted by the invertY parameter.

ymax

The "north" coordinate of the bounding box defined by the incoming tile coordinates. In the projection specified by srid. Not impacted by the invertY parameter.

env.XXX

An environment variable whose name is XXX

ctx.XXX

A context variable (typically an HTTP header) whose name is XXX

layer.XXX

If the layer includes a pattern with a placeholder of XXX, this is the replacement value from the used layer name

env.XXX values are inserted as-is without escaping. Environment variables are Operator input so this is intentional; it allows supplying an entire base URL including scheme, host, and path via {env.XXX}.

ctx.XXX and layer.XXX values come from the incoming request and are percent-encoded before being inserted. Placeholders before the first ? in the url are path-escaped, those after it are query-escaped. This prevents a request injecting a ?, #, or ../ to rewrite the upstream path or add query parameters. Note this means a value containing a / is encoded as %2F rather than treated as a path separator.

Also see the paramValidator option in the Layer configuration to restrict what values a pattern accepts in the first place.