Skip to content
getgeolens.com
GeoLens Docs

Tile Endpoint

GET
/tiles/{table_path}/{z}/{x}/{y}.pbf
 
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 either valid signature parameters (sig, exp, scope) or an embed token scoped to it, and answers 403 without one. 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, and answers 404 to other callers, so a refusal keeps its existence undisclosed. An unknown table is 404 too.

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. Three cases answer 429 with Retry-After: waiting past the tile pool’s connection budget, a tile query that outruns the pool’s per-command timeout, and exceeding a configured per-tenant concurrency limit. Any other failure serving the tile answers 503.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
table_path
required
Table Path
string
z
required
Z
integer
x
required
X
integer
y
required
Y
integer

Query Parameters

Section titled “ Query Parameters ”
sig
Any of:
string
exp
Any of:
integer
scope
Any of:
string
cols
Any of:
string

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Successful Response

400

Section titled “ 400 ”

Bad request — invalid query parameters or payload

Media type 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

Section titled “ 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.

Media type 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

Section titled “ 404 ”

Not found

Media type 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

Section titled “ 422 ”

Validation error

Media type 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

Section titled “ 429 ”

Too many requests — retry after the advertised interval

Media type 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

Section titled “ Headers ”
Retry-After
integer

Seconds until the request may be retried

500

Section titled “ 500 ”

Internal server error

Media type 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

Section titled “ 503 ”

Service unavailable — the database could not serve the request

Media type 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