Skip to content
getgeolens.com
GeoLens Docs

Cluster Tile Endpoint

GET
/tiles/clusters/{table_path}/{z}/{x}/{y}.pbf
 
curl --request GET \
  --url 'https://example.com/tiles/clusters/example/1/1/1.pbf?cluster_radius=48&cluster_max_zoom=14'

Serve a server-side clustered vector tile for a point dataset.

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

Authorization matches the plain vector tile route, in three cases. 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, so an expired token is rejected instead of being silently downgraded. A request sending no credential is served normally.

cluster_radius is a screen-pixel distance, the same units MapLibre’s clusterRadius uses, and cluster_max_zoom is the last zoom at which features are grouped. cols works as it does on the vector route, and the named columns are projected onto the unclustered features, so data-driven styling and popups keep working here too.

Requires a vector point dataset; another record type responds 400, as does a malformed table path or an out-of-range tile coordinate.

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
cluster_radius
Cluster Radius
integer
default: 48 >= 1 <= 256
cluster_max_zoom
Cluster Max Zoom
integer
default: 14 <= 22

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