GIS API Reference~

All endpoints on this page require login (session cookie or an API key). Endpoints that change data additionally require a permission — edit_settings, edit_controllers, or edit_plots depending on the resource — and endpoints tied to one map or facility further check that the caller's access group covers it (scope.can_operate). Each section below notes the permission where it isn't edit_settings.

Known duplication: POST /api/geo/designs, GET/DELETE /api/geo/designs/<uuid>, and GET/POST /api/geo/overlays are each defined twice in the codebase (once as a flask-restx resource, once as a plain Flask route). Because of Flask's route-registration order, only the flask-restx version actually runs for these five — the plain-route copies are unreachable. The behavior documented below is the one that runs. This duplication is an internal cleanup item, not part of the documented contract, and could change without notice.

Design Maps~

A "design" is one GeoMap row — a named map with its own center/zoom/layer state, holding all the shapes (sites, zones, facilities, devices) drawn on it. Creating, changing, deleting or restoring a map requires edit_settings, and the map must be inside the caller's granted scope (403 otherwise).

Overlays & Shapes (GeoJSON)~

"Overlays" are the GeoJSON features drawn on a map — sites, zones, facility outlines, device markers, equipment.

Details: POST /api/geo/overlays~

• Matches incoming features to existing rows by db_id, then node_id — everything else is derived from those.
• A feature missing from the payload is never deleted. Only an explicit deletes: [node_id_or_db_id, ...] list, or features: [] combined with allow_empty: true, removes rows. (A prior incident wiped shapes because "not present" was once treated as "delete".)
• An empty aot_device payload is refused outright instead of clearing every marker — device placement only goes through POST /api/geo/device/location.
• equipment features are stored as one bundled equipment_collection row (the whole set is replaced together), everything else is saved feature-by-feature. Because the bundle path clears the old set first, an empty equipment payload is refused unless allow_empty: true confirms the clear, and it reports how many rows it would have deleted.
• Transient sprinkler dot markers are dropped rather than stored, so a payload made only of them counts as empty.
• Geometry rules are checked before anything is written, and a single invalid feature aborts the whole save with a geometry error (equipment is exempt from that check).
• aot_type, device_id, and channel_id are stripped from the saved JSON blob — they're derived on read, not stored, so don't rely on round-tripping them.
• Response: {ok, count, id_map: {node_id: db_id}, stats: {deleted, updated, inserted}} (or a stats.mode: 'bulk_bundle' shape for the equipment path).

Search~

Device Binding~

A "binding" links a device (sensor or actuator) to a spatial slot — a zone polygon, a facility fitting, a sensor role, etc. Binding is a first-class object with history: ending one keeps the row (for audit) rather than deleting it. Writes require edit_settings.

Shared fields (spatial_kind, spatial_id, role, device_id, device_kind, channel_id, measurement_id) — see Details below.

Details: binding fields~

• spatial_kind: shape | fitting | actuator | sensor_role | weather.
• spatial_id: the slot identifier. For spatial_kind=shape this can be either a saved GeoShape.unique_id or a client-side node_id not yet persisted — the server resolves it either way (send map_uuid as well so the not-yet-saved lookup stays inside one map).
• role: what the slot is for (marker, area, actuator, sensor, ...). For shape slots, the role is derived server-side from the shape's own type — a client-supplied role is not trusted for shapes. A shape whose type isn't a place to hang a device on (only zone polygons and location markers are) is rejected outright.
• device_id: accepts a <device_uuid>::<channel> suffix; it's split and the channel becomes channel_id.
• device_kind is always re-validated/resolved server-side even if supplied.

Device Location, Lists & Detail~

Zones~

Sites~

Facilities~

A "facility" is a structure (greenhouse, barn, etc.) with an envelope (dimensions/material) and bound sensors/actuators.

Creating, cloning, deleting, computing, and applying require edit_settings; the read endpoints need only a login. Applying also requires operate permission for that facility. Commands and checks reach only the devices still bound to the facility — a severed binding is skipped.

Live runtime monitoring/control for a facility (real-time actuator state, safety setpoints, manual override, e-stop) is a separate API family under a different prefix — see Facility Runtime Control below.

Facility 3D Model Assets~

Reusable 3D models (primitives or imported .glb/.gltf files) that can be attached to a facility instead of its default parametric shape. All require login only (no extra permission check beyond that), and are scoped to owner_user_id = current_user.id for listing/creation (not enforced on get/update/delete/attach by id).

Facility Commissioning~

Post-install verification: run automated checks against a facility's actuators, then record a human verdict per actuator. Requires edit_settings except the result read. Checks are held in memory, so a restart discards one in progress. The measurement stage only advances while something feeds the check periodic sensor readings, and nothing currently supplies them — so a started check stays at its opening baseline stage: no per-actuator results appear and a verdict cannot be submitted yet.

Facility Runtime Control (/api/aot/facility, /api/aot/coordinator)~

This is a different URL prefix (/api/aot/, not /api/geo/) for the live side of a facility once its environment coordinator is running: status, safety-range setpoints, manual override, e-stop, and history. It's the same conceptual object as the facilities above (same facility_uuid), just a separate route family.

Cultivation Programs~

A "program" is a reusable growth-stage template (stages, GDD/DLI targets, irrigation/fertilizer schedule) that a plot follows. Writes require edit_plots.

Cultivation Plots~

A "plot" (구획) is one planting cycle on a piece of ground or a facility bay — its own stage timeline, targets, and schedule, independent of the shared program it follows. Writes require edit_plots.

Listing & detail~

Lifecycle & stage~

Schedule~

Splitting a zone into plots~

(The device-marker version of this splitter is POST /api/geo/device/split-apply, documented under Device Location, Lists & Detail — it reuses this same split-preview endpoint since the geometry math doesn't care what the pieces become.)

Manual Schedule~

A lightweight, non-device-actuating schedule entry (a note that a worker should do something on a date) — separate from the automatic device Scheduler.

Output Control (map popups)~

Parcel Import~

Importing real-world parcel/park boundaries as map shapes.

Aerial / Drone Image Overlays~

Georeferenced raster images (drone photos, aerial imagery) draped on the map. Upload and save require edit_controllers; the tiling poll only needs a signed-in session.

Proxy Services~

The server relays these external services so browser clients never see the upstream API key and don't hit CORS restrictions. All are GET, most cache the upstream response briefly (noted where known).

Settings~

Map Ordering~

Time & Solar~

Plot/Zone Journal (/geo/journal)~

Different prefix — these are under /geo/journal, not /api/geo. A journal is a generated report (GDD, DLI, day length, irrigation volume, weather) for a plot, zone, or site over a date range, built once in the background and then served from a stored snapshot.

Other~

• POST /api/tools/kma_lookup — a small standalone utility (different prefix, /api/tools/, not /api/geo/): nearest-neighbor lookup of the Korea Meteorological Administration's grid coordinates (nx, ny) for a given lat/lon.

Response Codes~