Tile Endpoint

GET

/tiles/{table_path}/{z}/{x}/{y}.pbf

const url = 'https://example.com/tiles/example/1/1/1.pbf';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/tiles/example/1/1/1.pbf

Serve a vector tile as gzipped MVT binary.

URL pattern: /tiles/data.{table_name}/{z}/{x}/{y}.pbf

A public, published dataset is readable without credentials. A non-public dataset needs valid signature parameters (sig, exp, scope), an embed token scoped to it, or an API key (X-Api-Key header or api_key query parameter) or bearer token for a caller with access to it. A tile served on the caller’s credentials is marked private, so no shared cache stores it, and a tile requested with api_key in the query is never marked public. A public dataset that is not yet published is readable by its owner, by an admin, with an embed token, or with valid signature parameters. A caller who cannot see the dataset gets the answer an unknown table gets, so a refusal never discloses that the table exists: 403 when an embed token, or an anonymous request’s signature parameters, did not authorize it, and 404 otherwise. A dataset without vector tiles, such as a raster, is 404 once the caller is authorized to see it.

A request that no capability authorized and that carried a credential which did not resolve is refused with 401 rather than served as an anonymous read. A request sending no credential is served normally.

cols is a runtime opt-in for additional attribute columns the client needs at all zooms (e.g. data-driven styling columns referenced by MapLibre paint expressions). Format: comma-separated column names. Each name is validated against the dataset column list before it flows into the MVT projection; invalid names are silently dropped. Does not need to be signed — sig already authorizes dataset access and cols can only project columns the caller already has REST access to.

A malformed table path or an out-of-range tile coordinate answers 400. A tile holding no features answers 204, and a repeat request whose If-None-Match matches answers 304. Where a deployment runs cold storage, a dataset still being restored answers 202 with a job id to poll. Requests answer 429 with Retry-After when the per-process capacity for uncached renders stays full for a short wait, tile-pool acquisition times out, a tile query exceeds the pool’s per-command timeout, or the configured per-tenant concurrency limit is exceeded. Any other failure serving the tile answers 503.

Authorizations

Parameters

Path Parameters

table_path

required

Table Path

string

required

integer

required

integer

required

integer

Query Parameters

sig

Any of:

string
null

string

exp

Any of:

integer
null

integer

scope

Any of:

string
null

string

cols

Any of:

string
null

string

Responses

200

The vector tile

application/vnd.mapbox-vector-tile

string format: binary

400

Bad request — invalid query parameters or payload

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Unauthenticated — a credential was supplied and could not be resolved (expired, revoked, or malformed). Sending no credential at all is not an error on these operations; they answer anonymously with the public subset. Neither is sending an unresolvable credential alongside a capability that authorizes the request on its own — a valid X-Embed-Token or a valid signed tile template (sig, exp, scope). Those are served and the unrelated credential is ignored.

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Not found

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Validation error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Too many requests — retry after the advertised interval

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Retry-After

integer

Seconds until the request may be retried

500

Internal server error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Service unavailable — the database could not serve the request

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Privacy Apache 2.0 getgeolens.com