API Endpoints¶

This page lists the most relevant application endpoints used by UI workflows.

Map APIs¶

Endpoint	Method	Auth	Purpose
/parcels/api/geojson/	GET	login	Map data (grid summaries or parcel features, supports ref_ts)
/parcels/api/extent/	GET	login	Bounding extent of visible parcels (supports ref_ts)
/parcels/api/geojson/<uuid:pk>/	GET	login	Single parcel version-row GeoJSON detail
/parcels/api/select/	POST	login	Shape + predicate based selection
/parcels/api/inline-update/<uuid:pk>/	POST	staff	Inline map edit that creates a new parcel version
/api/rasters/	GET	login	Active/ready DEM and landcover overlay catalog for map settings
/api/rasters/sample/	GET	login	Raster point sample at lat/lng for selected slug values (samples[] response)
/raster-tiles/<path>	GET	login	Raster tile endpoint backed by persistent RASTER_TILES_ROOT

Parcel Snapping APIs¶

Endpoint	Method	Minimum role	Purpose
/parcels/api/map-settings/snapping/	GET	authenticated user	Lazily create and return the current user's complete versioned settings
/parcels/api/map-settings/snapping/	PUT	authenticated user	Atomically replace the current user's complete settings; user IDs and unknown fields are rejected
/parcels/api/snapping/candidate/	POST	active-dataset Editor	Canonicalize one selected target vertex or edge position against current official geometry
/parcels/api/snapping/trace/	POST	active-dataset Editor	Return both authoritative exterior-ring directions between compatible anchors

Candidate and trace requests accept transient EPSG:4326 JSON points/references, not geometry files. PostGIS transforms them to the frozen projected parcel CRS for extraction, distance, fraction, path, and length work. Responses contain display coordinates only.

Stable errors are snapping_validation_error (400), snapping_permission_denied (403), scoped snapping_target_not_found (404), and snapping_target_stale (409). Inaccessible targets do not return parcel labels or geometry.

Parcel Overlap Advisory API¶

Endpoint	Method	Scope	Purpose
/parcels/api/overlap-check/	POST	authenticated subject access plus Editor	Transform WGS84 proposal polygons to storage CRS and return versioned, read-only conflict evidence

The server derives the dataset, stable parcel identity, and declared sources from fresh_create, parcel, or draft subject context. It rejects client dataset or source substitution. Responses include safe target labels, square-metre areas, WGS84 intersection geometry, complete counts, and at most 500 issue objects.

List/Search/Selection APIs¶

Endpoint	Method	Auth	Purpose
/parcels/search/ajax/	GET	login	Autocomplete search
/parcels/api/filtered-ids/	GET	login	IDs of full filtered result set
/parcels/batch/	POST	login	Batch export/delete/group edit (effective_at supported for write actions)

Dataset Selector APIs¶

Endpoint	Method	Auth	Purpose
/auth/profile/set-active-dataset/	POST	login	Validate + set user active dataset, then redirect to safe next/referrer
/auth/api/datasets/accessible/	GET	login	List active datasets accessible to current user with effective role
/api/datasets/accessible/	GET	login	Root alias of accessible-datasets API for UI integrations

Upload and Analytics APIs¶

Endpoint	Method	Auth	Purpose
/parcels/upload/	GET/POST	login	Upload/analyze vector data
/parcels/upload/<uuid:pk>/preview/	GET/POST	login	Preview + apply upload decision
/parcels/api/statistics/	POST	internal/staff	Statistics data for ECharts dashboard

Export/Download Endpoints¶

Endpoint	Method	Auth	Purpose
/parcels/download/	GET	login	Download visible parcels in GIS formats
/parcels/export/?format=csv|geojson	GET	internal/staff	Legacy export helpers

Parcel Topology Change Requests¶

All topology endpoints require login and dataset-scoped visibility. Inaccessible request and parcel identifiers return 404 without disclosing existence.

Endpoint	Method	Minimum role	Purpose
/parcels/api/change-requests/	GET	Viewer	List visible split and merge requests
/parcels/api/change-requests/	POST	Editor	Create a grouped request using operation_type, source_ids, and merge primary_source_id
/parcels/api/change-requests/<request_id>/	GET	Viewer	Return canonical sources, saved split line, outputs, projected areas, validation, events, lineage, and permitted actions
/parcels/api/change-requests/<request_id>/split-line/	PUT	Editor	Transform one display line to the storage CRS and atomically generate exactly two PostGIS split outputs
/parcels/api/change-requests/<request_id>/outputs/	PATCH	Editor	Update output identifiers and eligible business attributes; geometry keys are rejected
/parcels/api/change-requests/<request_id>/output-import/	POST	Editor	Import multipart .gpkg or .zip output geometry with a declared projected CRS and known linear units
/parcels/api/change-requests/<uuid>/actions/validate/	POST	Editor	Run authoritative PostGIS validation
/parcels/api/change-requests/<uuid>/actions/submit/	POST	Editor	Validate and submit the complete grouped request
/parcels/api/change-requests/<uuid>/actions/review-accept/	POST	Reviewer	Accept a submitted request for approval
/parcels/api/change-requests/<uuid>/actions/final-approve/	POST	Approver	Atomically retire sources, create results, transaction, and lineage
/parcels/api/change-requests/<uuid>/actions/reject/	POST	Reviewer/Approver	Reject with a required reason
/parcels/api/change-requests/<uuid>/actions/cancel/	POST	State-dependent	Cancel an uncommitted request
/parcels/api/change-requests/<uuid>/events/	GET	Viewer	Return scoped workflow-event history

Topology errors use a stable object with error, message, fields, and conflicting_source_ids. Final approval additionally returns transaction_id, effective_at, retired source IDs, resulting version IDs, and lineage edge IDs.

Permissions Notes¶

• All listed APIs require authentication unless explicitly public.
• Non-staff visibility generally resolves to: own parcels + public parcels.
• Active dataset filters are applied at the queryset layer for parcel APIs.
• Dataset selector options are server-derived; client-side filtering is convenience only.
• Read APIs default to active rows (valid_to IS NULL, record_status = active) unless explicit historical query params are used.
• ref_ts historical reads apply validity-window filters and exclude void rows.

URL Semantics for Detail Routes¶

• /parcels/<uuid:pk>/ resolves a specific immutable version row.
• /parcels/id/<parcel_id>/ resolves the current active row for that parcel ID.