Skip to content

API Reference

The routing layer is split into synchronous fast-paths (database transactions, mathematical verification) and asynchronous worker queues (point cloud segmentation, computer vision inference).

  • Base URL: http://localhost:8000/api/v1/cadastre
  • Interactive OpenAPI (Swagger): http://localhost:8000/docs
  • Raw Schema: http://localhost:8000/openapi.json

Note: All endpoints consume and emit application/json by default, except asynchronous ingest routes which accept multipart/form-data.

Note: Error responses return generic messages (e.g., "Internal processing error.") and never expose internal stack traces or SQL queries.

Synchronous Endpoints

1. Validate and Register Building

Executes Bayesian sensor height estimation, runs Isolation Forest anomaly detection, generates a deterministic 3D ULPIN, and persists a POLYHEDRALSURFACE Z geometry to PostGIS.

  • Method: POST
  • Path: /validate-building
  • Headers: Content-Type: application/json

Request Body

{
  "parent_2d_ulpin": "IN-DL-9999",
  "easting_x": 712000.0,
  "northing_y": 3170000.0,
  "footprint_coords": [
    [712000.0, 3170000.0],
    [712050.0, 3170000.0],
    [712050.0, 3170050.0],
    [712000.0, 3170050.0]
  ],
  "registered_height_m": 18.0,
  "sensor_evidence": [
    { "source_name": "Drone_DEM", "height_m": 18.1, "variance": 0.05 },
    { "source_name": "Ground_Survey", "height_m": 18.0, "variance": 0.01 }
  ]
}

Validation Rules

  • footprint_coords must contain at least 3 coordinate pairs to form a valid polygon.
  • variance must be a positive number.

Response (200 OK)

{
  "message": "Cadastral unit and evidence graph validated and saved.",
  "ulpin_identity": {
    "ulpin_3d": "IN-DL-9999-Z3891118852878484658-FF9669F4",
    "morton_index": 3891118852878484658,
    "checksum": "FF9669F4"
  },
  "anomaly_report": {
    "status": "VALID",
    "delta_h_m": 0.02,
    "sensor_confidence": 0.9087,
    "model_confidence_score": "92.1%",
    "diagnostics": "Measurements fall within normal historical distribution.",
    "engine": "Scikit-Learn IsolationForest"
  },
  "evidence_records_created": 2
}

Conflict Handling

If a ULPIN already exists in the database, the parcel's confidence_score and topology_status are updated (upsert). New evidence records are always appended.

2. In-Memory Volumetric Conflict Check

Performs an immediate geometric non-intersection check between two candidate 3D volumes using Shapely planar intersections and vertical Z-interval arithmetic.

  • Method: POST
  • Path: /check-conflict
  • Headers: Content-Type: application/json

Request Body

{
  "existing_parcel": {
    "parcel_id": "ULPIN-BASEMENT",
    "footprint_coords": [
      [0.0, 0.0], [0.0, 50.0], [50.0, 50.0], [50.0, 0.0]
    ],
    "z_min": -20.0,
    "z_max": -5.0
  },
  "proposed_infrastructure": {
    "parcel_id": "ULPIN-METRO-TUNNEL",
    "footprint_coords": [
      [-10.0, 20.0], [60.0, 20.0], [60.0, 30.0], [-10.0, 30.0]
    ],
    "z_min": -18.0,
    "z_max": -12.0
  }
}

Response (200 OK)

{
  "existing_parcel": "ULPIN-BASEMENT",
  "proposed_infrastructure": "ULPIN-METRO-TUNNEL",
  "egc_validation": {
    "conflict_detected": true,
    "parcel_a": "ULPIN-BASEMENT",
    "parcel_b": "ULPIN-METRO-TUNNEL",
    "affected_volume_m3": 3000.0,
    "depth_range": "-18.0m to -12.0m"
  }
}

3. Database Persistent Conflict Check

Executes a PostGIS SFCGAL query (ST_3DIntersects) to test whether two previously stored 3D polyhedral geometries physically collide.

  • Method: GET
  • Path: /db-conflict/{ulpin_1}/{ulpin_2}

Path Parameters

Parameter Type Description
ulpin_1 string 3D ULPIN identifier of the first parcel
ulpin_2 string 3D ULPIN identifier of the second parcel

Response (200 OK)

{
  "ulpin_1": "IN-DL-9999-Z3891118852878484658-FF9669F4",
  "ulpin_2": "IN-DL-9999-Z3891118852878484659-A1B2C3D4",
  "spatial_conflict_detected": false,
  "computation_engine": "PostGIS Native"
}

4. List 3D Parcels (Paginated)

Retrieves registered volumetric parcels with precomputed bounding coordinates and Well-Known Text (WKT) geometries for client-side rendering.

  • Method: GET
  • Path: /parcels

Query Parameters

Parameter Type Default Description
limit int 100 Number of parcels per page (max 500)
offset int 0 Number of parcels to skip

Response (200 OK)

{
  "total_parcels": 42,
  "limit": 100,
  "offset": 0,
  "parcels": [
    {
      "ulpin_3d": "IN-DL-9999-Z3891118852878484658-FF9669F4",
      "parent_2d_ulpin": "IN-DL-9999",
      "confidence_score": 0.93,
      "topology_status": "VALID",
      "geometry_wkt": "POLYHEDRALSURFACE Z (((712000 3170000 0, ...)))",
      "bounds": {
        "x_min": 712000.0,
        "x_max": 712050.0,
        "y_min": 3170000.0,
        "y_max": 3170050.0,
        "z_min": 0.0,
        "z_max": 18.02
      }
    }
  ]
}

Asynchronous Task Endpoints

Compute-heavy segmentation jobs are offloaded to Celery to prevent event-loop latency.

Upload Constraints

All file uploads are subject to: - Maximum file size: 500 MB - LiDAR allowed extensions: .ply, .pcd, .las, .laz - Drone image allowed extensions: .jpg, .jpeg, .png, .tif, .tiff

Files exceeding the size limit receive a 413 Payload Too Large response. Invalid file types receive a 422 Unprocessable Entity response.

1. Ingest Point Cloud

Dispatches raw point cloud data for ground plane subtraction (RANSAC) and structural cluster extraction (DBSCAN) using Open3D.

  • Method: POST
  • Path: /ingest-lidar
  • Query Parameters: ulpin_id (string, required)
  • Headers: Content-Type: multipart/form-data

Form Data

Key Type Description
file binary Binary point cloud file (.ply, .pcd, .las, .laz)

Response (200 OK)

{
  "ulpin_id": "IN-DL-9999",
  "message": "Point cloud queued for RANSAC/DBSCAN spatial processing.",
  "job_id": "8f3b2d11-5e6a-4d22-b91c-1a2b3c4d5e6f",
  "status_endpoint": "/api/v1/cadastre/job-status/8f3b2d11-5e6a-4d22-b91c-1a2b3c4d5e6f"
}

2. Ingest Aerial Drone Image

Submits aerial orthophotos to YOLOv8-Seg for building mask inference and Ramer-Douglas-Peucker (RDP) footprint simplification.

  • Method: POST
  • Path: /ingest-drone
  • Query Parameters: ulpin_id (string, required)
  • Headers: Content-Type: multipart/form-data

Form Data

Key Type Description
file binary Image file (.jpg, .jpeg, .png, .tif, .tiff)

Response (200 OK)

{
  "ulpin_id": "IN-DL-9999",
  "message": "Drone imagery queued for YOLOv8 neural inference.",
  "job_id": "2a4b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
  "status_endpoint": "/api/v1/cadastre/job-status/2a4b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d"
}

3. Query Task Status

Polls the task lifecycle state and extracts resultant geometries upon job completion.

  • Method: GET
  • Path: /job-status/{job_id}

Response: Task Pending / Running (200 OK)

{
  "job_id": "2a4b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
  "status": "PENDING (In Queue)"
}

Response: Task Completed (200 OK)

{
  "job_id": "2a4b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
  "status": "COMPLETED",
  "result": {
    "ulpin_id": "IN-DL-9999",
    "polygon_data": {
      "source_image": "/tmp/mimi_uploads/image.jpg",
      "footprint_geometry": [[712000.0, 3170000.0], [712050.0, 3170000.0]],
      "polygon_vertices": 4,
      "is_georeferenced": false,
      "ml_engine": "YOLOv8-Seg + RDP Simplification"
    }
  }
}

Response: Task Failed (200 OK)

{
  "job_id": "2a4b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
  "status": "FAILED",
  "error": "Vision Pipeline: No valid structures detected in imagery."
}