Aggregate Endpoint
const url = 'https://example.com/datasets/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/aggregate/';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"filter":{},"bbox":[1],"op":"count"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/datasets/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/aggregate/ \ --header 'Content-Type: application/json' \ --data '{ "filter": {}, "bbox": [ 1 ], "op": "count" }'Compute one exact aggregate over a dataset’s rows, for a widget.
Anonymous callers can read public, published datasets; X-Embed-Token
authorizes datasets in the token’s scope. Other datasets return 404.
With bbox, a view the planner expects to hold more than 500,000 rows
is refused with 422 and the code too_wide rather than approximated. A
bbox that contains the whole dataset is answered as the whole layer.
Refusals carry a code in detail: too_wide, invalid_column,
invalid_filter, no_geometry, query_timeout,
query_data_error, result_too_large, and with 429 query_busy
(this caller already has two aggregates running) or query_at_capacity.
Clients should keep at most two requests in flight per caller and retry a 429 after 200-400 ms with jitter.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Header Parameters
Section titled “ Header Parameters ”Request Bodyrequired
Section titled “ Request Bodyrequired ”object
object
object
object
Responses
Section titled “ Responses ”Successful Response
object
Always false: a view too wide to count exactly is refused.
object
object
Always false: a view too wide to count exactly is refused.
The requested statistics; one over no rows is null.
sum, min and max are exact: a number when JSON can carry it
exactly, else text. avg is a float, or text for NaN and infinity.
object
Always false: a view too wide to count exactly is refused.
object
Always false: a view too wide to count exactly is refused.
object
Equal-width bins over the finite values; empty with none.
object
object
Always false: a view too wide to count exactly is refused.
Example
{ "approximate": false, "op": "count"}Bad request — invalid query parameters or payload
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 valid X-Embed-Token that authorizes the request on its own. That request is served and the unrelated credential is ignored.
Forbidden — caller lacks access to this resource
Not found
Validation error
Too many requests — retry after the advertised interval
Headers
Section titled “ Headers ”Seconds until the request may be retried
Internal server error
Service unavailable — the database could not serve the request