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 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. It answers 403 to a request carrying none of these and 404 to a caller without access. 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, and answers 404 to other callers, so a refusal keeps its existence undisclosed. An unknown table is 404 too, and so is a dataset without vector tiles, such as a raster, 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 is full, 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

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