Datasets - Analysis

Analysis Preview Endpoint

Changed on

Run a parameterized PostGIS operation and return a GeoJSON preview.

Synchronous, read-only, and capped: results are for on-map preview, not persistence — use the materialize endpoint to save output as a dataset.

post/datasets/{dataset_id}/analysis/preview/

Request

  • The document declares no server URL.
  • Auth: one of:
    • OAuth 2 (password, token URL /api/auth/login)
    • API key in header X-Api-Key
    • API key in query parameter api_key

Path parameters

dataset_idstring uuid required

Request body

operation'buffer' | 'centroid' | 'clip' | 'spatial_join' | 'measure' | 'select_by_location' | 'intersect' required
distance_metersnumber nullable

Buffer distance in meters (buffer only)

maskobject nullable

GeoJSON Polygon or MultiPolygon geometry in EPSG:4326 (clip and select_by_location)

mask_dataset_idstring uuid nullable

Polygon dataset supplying the second layer: the area clipped to, selected against, or overlaid with. For clip and select_by_location it is the alternative to mask; for intersect it is REQUIRED and mask is rejected, because an overlay carries the second layer's attributes onto its output and a drawn polygon has none.

join_dataset_idstring uuid nullable

Dataset to join against; each source feature gains a count of the features from it that intersect (spatial_join only)

join_fieldsstring[] nullable

Columns to copy from the intersecting join feature, prefixed 'join_' in the output. Ties break on the lowest join-layer gid (spatial_join only)

bboxnumber[] nullable

[minx, miny, maxx, maxy] in EPSG:4326, typically the map's current viewport. When present, only source features intersecting the envelope are considered before the preview's row cap applies, so a capped result reflects what is on screen rather than an arbitrary sample in ingest order. Applies to every operation, not just one, so it is deliberately absent from _ANALYSIS_PARAM_OWNERS — omit it to preview the whole dataset, unchanged from before this field existed.

filterobject nullable

CQL2-JSON filter on the source dataset, in the language /collections/{dataset_id}/items accepts as filter-lang=cql2-json. Only the features it keeps are analysed, counted, and checked against the operation's size limit.

mask_filterobject nullable

CQL2-JSON filter on the mask_dataset_id layer: only its matching features form the mask or overlay. Requires mask_dataset_id.

join_filterobject nullable

CQL2-JSON filter on the join layer: only its matching features are joined (spatial_join only).

Response

Successful Response

geojsonobject required
feature_countinteger required
truncatedboolean required
bboxnumber[] nullable
source_feature_countinteger nullable

Total feature count of the source dataset (1:1 operations only; null when the operation filters rows, e.g. clip). When the request carried a bbox or a filter this is a live count of the rows intersecting the bbox and matching the filter rather than the dataset's cached whole-table total. It is also null, like match_count, when that live count could not be computed within the query budget

match_countinteger nullable

Exact total across the WHOLE source, not just the previewed features — WHOLE meaning the request's bbox when one was sent, the same sense source_feature_count uses that word, and always within the request's layer filters. What it counts is per-operation, so read it against the operation you sent rather than as one number: select_by_location gives the selected source features and intersect gives the output pieces, and for both of those it IS the output total; spatial_join gives intersecting source/join PAIRS, which is NOT the output total, because the join keeps every source row (use source_feature_count for that operation). intersect and spatial_join both scope this total to a bbox on the request; select_by_location's count is a separate uncapped query the request's bbox does not reach, so it stays unscoped even though its preview rows are viewport-limited too. Null for operations that report no such total, and when the count could not be computed within the query budget

Changes

  • a9f1b20e3ac9Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property