Design APIs That Understand Space

What a spatial API must preserve

Coordinates are useful only when their meaning survives the boundary between systems.

A spatial API describes entities and relationships in a reference frame. That may mean geographic features on Earth, poses in a headset session, objects in a scene graph, routes through a building, or detections in an image. The contract should name the entity, coordinate frame, units, time, geometry, and confidence so a client can use the value without reverse-engineering hidden assumptions.

The strongest designs distinguish raw observations from normalized state and derived semantics. A camera sees pixels; a detector proposes an object; a depth pipeline estimates position; a domain service identifies the asset; a user interface explains the result. Keeping those layers separate makes errors traceable and allows one component to improve without rewriting the entire product.

The six-layer spatial stack

A reusable architecture can be organized into acquisition, normalization, spatial indexing, semantic services, application state, and delivery. Acquisition reads sensors, files, maps, engine events, or upstream APIs. Normalization converts values into canonical units and frames. Spatial indexes accelerate containment, proximity, ray, route, and visibility queries. Semantic services attach domain meaning. Application state manages durable entities, permissions, revisions, and workflows. Delivery exposes HTTP, streams, SDKs, or in-process interfaces.

These layers can run on one device or be distributed across edge and cloud. High-frequency pose and collision usually stay local. Shared maps, durable anchors, large indexes, and cross-device state often belong in a service. The right boundary follows latency, privacy, bandwidth, and consistency requirements rather than organizational charts.

Canonical entity and pose model

Every durable entity should have a stable ID, type, revision, lifecycle, and one or more spatial representations. A pose needs position, orientation, frame ID, timestamp, units, and quality. Geometry needs an explicit type and precision rules. Attributes should carry domain state rather than being hidden in filenames, object names, or runtime handles.

Keep runtime identity separate from product identity. A WebXR object, OpenXR space, Unity GameObject, Unreal Actor, AR anchor, or map feature handle may be destroyed and recreated. The product-level entity remains stable and can be resolved into a new runtime representation.

{
  "id": "asset-2048",
  "type": "equipment",
  "revision": 17,
  "pose": {
    "frame": "facility:west-wing:v3",
    "position_m": [12.84, 1.05, -6.22],
    "orientation_xyzw": [0, 0.7071, 0, 0.7071],
    "observed_at": "2026-10-20T18:30:00Z",
    "accuracy_m": 0.08
  }
}

Core query vocabulary

Common spatial operations include within a bounding region, within a radius, nearest N, intersects geometry, contains point, visible from pose, hit by ray, connected by route, and changed after revision. Use consistent names and response metadata across collections. A client should not learn a new pagination and filter style for every entity type.

Queries need limits. State maximum area, distance, geometry complexity, result count, and time window. Return the applied query, truncation, continuation cursor, frame, units, and freshness. For high-rate updates, define subscription ordering, replay, reconnection, and whether events are full snapshots or deltas.

Build for transformation and uncertainty

Spatial products frequently combine geographic coordinates, local map frames, device tracking spaces, camera coordinates, and engine worlds. Centralize transformations in tested adapters. Record axes, handedness, scale, origin, and time. A transform that was valid before a tracking reset may not be valid after it.

Accuracy is not the number of decimal places. Include error radius, tracking state, classifier confidence, or alternatives as appropriate. Applications can then choose to display an approximate result, ask for another observation, or block a high-risk action until quality improves.

Security and privacy are spatial features

Precise location, camera frames, depth maps, room meshes, and persistent anchors reveal physical context. Minimize collection, process locally where practical, scope tokens to resources and operations, and apply object- and region-level authorization. A broad bounding-box query should not become a way to enumerate private facilities or people.

Design deletion, retention, sharing, moderation, and emergency removal before launch. Spatial content can affect the physical world, so provenance, confidence, and authority should be visible to users. Official instructions, collaborator annotations, and untrusted public content should not appear identical.

A sensible first release

Start narrow and precise. A small contract that clearly answers what, where, relative to what, when, and with what confidence is more valuable than a broad API that makes clients guess.

• One or two canonical frames with documented axes and units.
• A small set of typed entities with stable IDs and revisions.
• Bounding, proximity, and detail endpoints with cursor pagination.
• Explicit timestamps and quality fields for every observation.
• One transform service or adapter with round-trip tests.
• Capability and permission fields that guide client behavior.
• Immutable asset versions and durable anchor records.
• Synthetic fixtures for edge cases, privacy review, and load tests.