Geospatial Operations

Split Geometry

POST `/api/forest/geo/operations`

Divide a single Level 4 geometry into two new geometries using a cut polygon. Authentication: Required
Permissions: forest-patrimony:UPDATE

Request Body

operation

string

required

Operation type: "split"

sourceLevel4Id

string

required

UUID of the Level 4 geometry to split

cutGeometry

object

required

GeoJSON geometry defining the cut area (Polygon or MultiPolygon)

{
  "type": "Polygon",
  "coordinates": [[[lng1, lat1], [lng2, lat2], ...]]
}

newItems

array

required

Array of exactly 2 objects defining the resulting geometries:

newItems[].code

string

required

New Level 4 code for the resulting geometry

newItems[].name

string

required

Name for the resulting geometry

newItems[].type

string

Level 4 type: RODAL, PARCELA, ENUMERATION, UNIDAD_DE_MANEJO, CONUCO, OTRO_USODefaults to source geometry type

newItems[].fscCertificateStatus

string

FSC certification status: SI or NODefaults to source status

newItems[].currentLandUseName

string

Current land use (must exist in LandUseType configuration)

newItems[].previousLandUseName

string

Previous land use name for variation tracking

variationDate

string

Date of the operation (ISO 8601 format). Defaults to current date.

variationNotes

string

Notes for patrimonial variation audit trail

Response

operation

string

Operation type: "split"

sourceLevel4Id

string

UUID of the original (now inactive) geometry

createdLevel4Ids

array

Array of 2 UUIDs for the newly created geometries

Example: Split a Stand

cURL

curl -X POST https://api.confor.com/api/forest/geo/operations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "split",
    "sourceLevel4Id": "550e8400-e29b-41d4-a716-446655440000",
    "cutGeometry": {
      "type": "Polygon",
      "coordinates": [[[-70.5, 18.5], [-70.4, 18.5], [-70.4, 18.4], [-70.5, 18.4], [-70.5, 18.5]]]
    },
    "newItems": [
      {
        "code": "N4-001-A",
        "name": "Rodal Norte",
        "currentLandUseName": "BOSQUE"
      },
      {
        "code": "N4-001-B",
        "name": "Rodal Sur",
        "currentLandUseName": "BOSQUE"
      }
    ],
    "variationDate": "2026-03-09",
    "variationNotes": "División administrativa para mejor gestión"
  }'

Response

{
  "operation": "split",
  "sourceLevel4Id": "550e8400-e29b-41d4-a716-446655440000",
  "createdLevel4Ids": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ]
}

The original geometry is marked as isActive: false and its forest_geometry_n4 record is closed with valid_to timestamp.

Merge Geometries

POST `/api/forest/geo/operations`

Consolidate two adjacent Level 4 geometries into a single geometry. Authentication: Required
Permissions: forest-patrimony:UPDATE

Request Body

operation

string

required

Operation type: "merge"

sourceLevel4Ids

array

required

Array of exactly 2 Level 4 UUIDs to merge. Both must:

Belong to the same Level 3
Be active (isActive: true)
Belong to the user’s organization

newCode

string

required

Code for the resulting merged geometry

variationDate

string

Date of the operation (ISO 8601 format). Defaults to current date.

variationNotes

string

Notes for patrimonial variation audit trail

Response

operation

string

Operation type: "merge"

sourceLevel4Ids

array

Array of 2 UUIDs for the original (now inactive) geometries

createdLevel4Id

string

UUID of the newly created merged geometry

Example: Merge Two Stands

cURL

curl -X POST https://api.confor.com/api/forest/geo/operations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "merge",
    "sourceLevel4Ids": [
      "660e8400-e29b-41d4-a716-446655440001",
      "660e8400-e29b-41d4-a716-446655440002"
    ],
    "newCode": "N4-001-MERGED",
    "variationDate": "2026-03-09",
    "variationNotes": "Consolidación de rodales pequeños"
  }'

Response

{
  "operation": "merge",
  "sourceLevel4Ids": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ],
  "createdLevel4Id": "770e8400-e29b-41d4-a716-446655440003"
}

Merged geometry name is automatically generated as "{Name A} + {Name B}". Other attributes are inherited from the first source geometry.

Get Level 4 Geometry

GET `/api/forest/geo/level4?id={level4Id}`

Retrieve a Level 4 geometry with its current spatial data. Authentication: Required
Permissions: forest-patrimony:READ

Query Parameters

string

required

UUID of the Level 4 geometry

Response

string

Level 4 UUID

level2Id

string

Parent Level 2 UUID

level3Id

string

Parent Level 3 UUID

code

string

Level 4 code

name

string

Level 4 name

type

string

Level 4 type (e.g., RODAL, PARCELA)

fscCertificateStatus

string

FSC certification status: SI or NO

currentLandUseName

string

Current land use

previousLandUseName

string

Previous land use (if changed)

totalAreaHa

number

Total area in hectares (calculated from geometry)

geometry

object

GeoJSON geometry object (MultiPolygon in EPSG:4326)

{
  "type": "MultiPolygon",
  "coordinates": [[[[lng, lat], ...]]]
}

Example: Fetch Geometry

cURL

curl -X GET "https://api.confor.com/api/forest/geo/level4?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "level2Id": "org_n2_001",
  "level3Id": "org_n3_001",
  "code": "N4-001",
  "name": "Rodal Principal",
  "type": "RODAL",
  "fscCertificateStatus": "SI",
  "currentLandUseName": "BOSQUE",
  "previousLandUseName": null,
  "totalAreaHa": 15.42,
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [[[[--70.5, 18.5], [-70.4, 18.5], [-70.4, 18.4], [-70.5, 18.4], [-70.5, 18.5]]]]
  }
}

Update Level 4 Geometry

PATCH `/api/forest/geo/level4`

Update Level 4 attributes and/or geometry. Authentication: Required
Permissions: forest-patrimony:UPDATE

Request Body

level4Id

string

required

UUID of the Level 4 to update

code

string

New code (must be unique within Level 3)

name

string

New name

type

string

New type: RODAL, PARCELA, ENUMERATION, UNIDAD_DE_MANEJO, CONUCO, OTRO_USO

fscCertificateStatus

string

FSC status: SI or NO

currentLandUseName

string

New land use (triggers patrimonial variation if changed)

previousLandUseName

string

Previous land use for variation tracking

polygon

object

New geometry (Polygon or MultiPolygon). If provided:

Old geometry is marked inactive
New geometry is inserted
Metrics (area, centroid) are recalculated
landUseChangeDate is updated

Response

Returns the updated Level 4 record.

Example: Update Land Use

cURL

curl -X PATCH https://api.confor.com/api/forest/geo/level4 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "level4Id": "550e8400-e29b-41d4-a716-446655440000",
    "currentLandUseName": "PLANTACION",
    "previousLandUseName": "BOSQUE"
  }'

Delete Level 4 Geometry

DELETE `/api/forest/geo/level4`

Soft-delete a Level 4 geometry (marks as inactive). Authentication: Required
Permissions: forest-patrimony:DELETE

Request Body

level4Id

string

required

UUID of the Level 4 to delete

Response

message

string

Deletion confirmation message

Cannot delete a Level 4 that has related Level 5 records. Returns 409 Conflict if children exist.

Geospatial Processing Details

Split Operation Workflow

Validate Source: Verify source Level 4 exists and is active
Cut Geometry: Use PostGIS ST_Intersection and ST_Difference to split:
- Part A = Intersection of source geometry with cut geometry
- Part B = Difference of source geometry and cut geometry
Deactivate Source: Mark original geometry as inactive
Create New Records: Insert two new Level 4 records with inherited attributes
Store Geometries: Insert new geometries into forest_geometry_n4
Calculate Metrics: Compute area and centroid for both parts
Track Variations: Create patrimonial variation records if land use changed

Merge Operation Workflow

Validate Sources: Ensure both Level 4s exist, are active, and belong to same Level 3
Union Geometries: Use PostGIS ST_UnaryUnion(ST_Collect(...)) to merge
Deactivate Sources: Mark both original geometries as inactive
Create New Record: Insert merged Level 4 with combined attributes
Store Geometry: Insert merged geometry into forest_geometry_n4
Calculate Metrics: Compute area and centroid for merged geometry
Track Variation: Create patrimonial variation record

All geospatial operations run within database transactions to ensure atomicity.

Automated Metric Calculation

Whenever a geometry is created or updated, the following metrics are automatically calculated:

Total Area (Ha): Computed using PostGIS geography cast for accurate ellipsoidal calculations
Centroid: Latitude and longitude of the geometric center (EPSG:4326)
Land Use Totals: Organization-level land use surface totals are synchronized

Example: Area Calculation

SELECT 
  ST_Area(geom::geography) / 10000 AS superficie_ha,
  ST_Y(ST_Centroid(geom)) AS lat,
  ST_X(ST_Centroid(geom)) AS lon
FROM forest_geometry_n4
WHERE level4_id = '...' AND is_active = TRUE;

Patrimonial Variation Tracking

All split, merge, and land use change operations automatically create records in the LandPatrimonialVariation table:

Previous Land Use: Captured before the operation
New Land Use: After the operation
Affected Area (Ha): Calculated from geometry
Variation Kind: INCREMENTO (change) or SIN_CAMBIO (no change)
Status: Always PENDIENTE (pending valuation)
Reference Values: Initialized to 0, updated later by valuation process

Use the Patrimonial Variations API to review and approve these tracked changes.

Error Responses

Status Code	Error	Cause
`400`	`Payload inválido`	Missing required fields or invalid geometry type
`403`	`No autorizado`	Insufficient permissions or organization mismatch
`404`	`Rodal no encontrado`	Level 4 ID doesn’t exist or is inactive
`409`	`Ya existe un rodal con ese código`	Code uniqueness violation within Level 3
`400`	`Solo se pueden consolidar rodales del mismo Nivel 3`	Merge attempted across different Level 3s
`400`	`La geometría se superpone con el rodal activo`	New geometry overlaps with existing active geometry

Geospatial Import - Bulk import geometries from shapefiles
Forest Patrimony - Manage forest hierarchy (Level 2/3/4/5)

Authentication

Organizations

Forest Patrimony

Biological Assets

Geospatial

Configuration

Geospatial Operations

Split Geometry

POST `/api/forest/geo/operations`

Request Body

Response

Example: Split a Stand

Merge Geometries

POST `/api/forest/geo/operations`

Request Body

Response

Example: Merge Two Stands

Get Level 4 Geometry

GET `/api/forest/geo/level4?id={level4Id}`

Query Parameters

Response

Example: Fetch Geometry

Update Level 4 Geometry

PATCH `/api/forest/geo/level4`

Request Body

Response

Example: Update Land Use

Delete Level 4 Geometry

DELETE `/api/forest/geo/level4`

Request Body

Response

Geospatial Processing Details

Split Operation Workflow

Merge Operation Workflow

Automated Metric Calculation

Patrimonial Variation Tracking

Error Responses

Build docs developers (and LLMs) love

Authentication

Organizations

Forest Patrimony

Biological Assets

Geospatial

Configuration

​Split Geometry

​POST /api/forest/geo/operations

​Request Body

​Response

​Example: Split a Stand

​Merge Geometries

​POST /api/forest/geo/operations

​Request Body

​Response

​Example: Merge Two Stands

​Get Level 4 Geometry

​GET /api/forest/geo/level4?id={level4Id}

​Query Parameters

​Response

​Example: Fetch Geometry

​Update Level 4 Geometry

​PATCH /api/forest/geo/level4

​Request Body

​Response

​Example: Update Land Use

​Delete Level 4 Geometry

​DELETE /api/forest/geo/level4

​Request Body

​Response

​Geospatial Processing Details

​Split Operation Workflow

​Merge Operation Workflow

​Automated Metric Calculation

​Patrimonial Variation Tracking

​Error Responses

​Related Endpoints

Build docs developers (and LLMs) love

Split Geometry

POST `/api/forest/geo/operations`

Request Body

Response

Example: Split a Stand

Merge Geometries

POST `/api/forest/geo/operations`

Request Body

Response

Example: Merge Two Stands

Get Level 4 Geometry

GET `/api/forest/geo/level4?id={level4Id}`

Query Parameters

Response

Example: Fetch Geometry

Update Level 4 Geometry

PATCH `/api/forest/geo/level4`

Request Body

Response

Example: Update Land Use

Delete Level 4 Geometry

DELETE `/api/forest/geo/level4`

Request Body

Response

Geospatial Processing Details

Split Operation Workflow

Merge Operation Workflow

Automated Metric Calculation

Patrimonial Variation Tracking

Error Responses

Related Endpoints