Wildvine API Docs

Wildvine API Reference

REST API for UPM Precision Biodiversity System — Pre-Felling inventory, Candidate Tree selection, species trends and forecast projections.

BASE URL https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com

Business Rules

Rules applied by the BDS simulation engine when filtering candidate trees.

Pre-Felling filter

DBH >= 30 cm

Dipterocarp cutting limit

DBH >= 65 cm

Non-dipterocarp limit

DBH >= 55 cm

Chengal cutting limit

DBH >= 70 cm

CT eligible groups

Dipterocarp, Non-dipterocarp, Chengal

Vulnerable exclusion

redlist != "0"

BDS Endpoints

Simulation endpoints powering the BDS Page 1 — Pre-Felling inventory and Candidate Trees.

GET /v3/bds/compartments List available compartment sizes ▶

Parameters

Response

Example

No parameters required. Returns static list. No AWS credentials needed.

Response Schema

{
  "data": [
    {
      "compartment_hectare": 2,    // hectare value for dropdown
      "location_id":        1     // internal Athena location_id
    }
  ]
}

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/bds/compartments"

Response

{
  "data": [
    { "compartment_hectare": 2,  "location_id": 1 },
    { "compartment_hectare": 50, "location_id": 2 }
  ]
}

GET /v3/bds/years Available census years for a compartment ▶

Parameters

Response

Example

Name	Type	Required	Description
compartment_hectare	integer	Required	Compartment size. Must be `2` or `50`.

200 — Success

{
  "data": [1971, 1979, 1984, 1989, ...],  // sorted census years
  "compartment_hectare": 50
}

400 — Invalid compartment

{ "detail": "compartment_hectare=99 is not valid. Valid options: [2, 50]" }

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/bds/years?compartment_hectare=50"

Response

{
  "data": [1971, 1979, 1984, 1989, 1991, 1993, 1997, 1999, 2003, 2012, 2015, 2017, 2019, 2021],
  "compartment_hectare": 50
}

GET /v3/bds/simulation Full BDS Page 1 data — Pre-Felling + Candidate Trees ▶

Parameters

Schema

Response

Example

Name	Type	Required	Description
year	integer	Required	Census year, e.g. `2021`. Use `/v3/bds/years` to get valid values.
compartment_hectare	integer	Required	Compartment size in hectares. Must be `2` or `50`.

Response Schema

{
  "pre_felling": {
    "tree_density":               { "value": integer, "change_pct": integer },
    "tree_density_per_ha":        { "value": float,   "change_pct": integer },
    "volume_m3_per_ha":           { "value": float,   "change_pct": integer },
    "basal_area_m2_per_ha":       { "value": float,   "change_pct": integer },
    "total_biomass_t":             { "value": float,   "change_pct": integer },
    "total_carbon_t":              { "value": float,   "change_pct": integer },
    "dipterocarp_density_per_ha":  { "value": float,   "change_pct": integer }
  },
  "distributions": {
    "species_group_density": [
      { "group": string, "value": integer }
    ],
    "dbh_size_class_density": [
      { "class": "30-45cm" | "45-60cm" | "60-75cm" | "75-90cm" | ">90cm", "value": integer }
    ]
  },
  "candidate_trees": {
    "summary": {
      "tree_density":        integer,
      "tree_density_per_ha": float,
      "volume_m3":           float,
      "basal_area_m2":       float,
      "total_biomass_t":     float,
      "total_carbon_t":      float,
      "price_rm":            float
    },
    "species_breakdown": [{
      "species_group":           string,
      "cutting_limit_cm":        float,
      "tree_density":            integer,
      "tree_density_per_ha":     float,
      "volume_m3":               float,
      "volume_m3_per_ha":        float,
      "basal_area_m2":           float,
      "basal_area_m2_per_ha":    float,
      "total_biomass_t":         float,
      "total_biomass_t_per_ha":  float,
      "total_carbon_t":          float,
      "total_carbon_t_per_ha":   float
    }]
  },
  "meta": {
    "compartment_hectare": integer,
    "year":                integer,
    "updated_at":          string (ISO 8601)
  }
}

change_pct — percentage of the PF metric relative to all trees (no DBH filter) in the same dataset.
e.g. tree_density.change_pct = 74 means DBH≥30cm trees = 74% of all trees.

200 — Success (abbreviated)

{
  "pre_felling": {
    "tree_density":               { "value": 3750,   "change_pct": 91 },
    "tree_density_per_ha":        { "value": 75.0,   "change_pct": 91 },
    "volume_m3_per_ha":           { "value": 138.52, "change_pct": 86 },
    "basal_area_m2_per_ha":       { "value": 15.26,  "change_pct": 49 },
    "total_biomass_t":             { "value": 267.46, "change_pct": 63 },
    "total_carbon_t":              { "value": 125.71, "change_pct": 63 },
    "dipterocarp_density_per_ha":  { "value": 21.1,   "change_pct": 28 }
  },
  "distributions": {
    "species_group_density": [
      { "group": "Non-dipterocarp", "value": 2631 },
      { "group": "Dipterocarp",     "value": 983  },
      { "group": "Chengal",         "value": 72   },
      { "group": "Pioneer",         "value": 64   }
    ],
    "dbh_size_class_density": [
      { "class": "30-45cm", "value": 2307 },
      { "class": "45-60cm", "value": 794  },
      { "class": "60-75cm", "value": 320  },
      { "class": "75-90cm", "value": 167  },
      { "class": ">90cm",   "value": 162  }
    ]
  },
  "candidate_trees": {
    "summary": {
      "tree_density": 700, "tree_density_per_ha": 14.0,
      "volume_m3": 4255.64, "basal_area_m2": 366.22,
      "total_biomass_t": 6323.56, "total_carbon_t": 2972.07,
      "price_rm": 365386.78
    },
    "species_breakdown": [
      { "species_group": "Dipterocarp",     "cutting_limit_cm": 65, "tree_density": 262, /* ... */ },
      { "species_group": "Non-dipterocarp", "cutting_limit_cm": 55, "tree_density": 396, /* ... */ },
      { "species_group": "Chengal",         "cutting_limit_cm": 70, "tree_density": 42,  /* ... */ }
    ]
  },
  "meta": { "compartment_hectare": 50, "year": 2021, "updated_at": "2026-05-06T10:00:00Z" }
}

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/bds/simulation?year=2021&compartment_hectare=50"

v3 Endpoints

General forest inventory endpoints. All support optional filters: years, location_ids, species_groups, dbh_size_classes, protected_tree, scientific_name.

GET /v3/overview Forest inventory summary + forecast ▶

Parameters

Example

Name	Type	Required	Description
years	integer[]	Optional	Filter by census year(s), e.g. `?years=2017&years=2021`
location_ids	integer[]	Optional	`1` = 2ha plot, `2` = 50ha plot
species_groups	string[]	Optional	e.g. `Dipterocarp`, `Chengal`
dbh_size_classes	string[]	Optional	e.g. `30_45`, `45_60`, `60_75`, `75_90`, `90`
protected_tree	string[]	Optional	Redlist values, e.g. `VU`, `EN`. Use `0` for non-protected.
scientific_name	string[]	Optional	Partial match on scientific name

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/overview?years=2021&location_ids=2"

Response shape

{
  "data": {
    "summary": { "tree_density": 4120, "tree_density_per_ha": 82.4, "volume_per_ha": 161.2, /* ... */ },
    "tree_density_by_species_group": [ { "species_group": "Non-dipterocarp", "tree_density": 2800 }, /* ... */ ],
    "tree_density_by_dbh_size_class": [ { "dbh_size_class": "30_45", "tree_density": 2307 }, /* ... */ ],
    "forecast_tree_density_by_species_group": [ /* 30-year projection */ ],
    "forecast_tree_density_by_dbh_size_class": [ /* 30-year projection */ ]
  }
}

GET /v3/trends Time-series metrics across census years ▶

Parameters

Example

Name	Type	Required	Description
view_by	string	Optional	`species_groups` or `dbh_size_classes` (default)
years	integer[]	Optional	Subset of years to return. Defaults to latest 5.
location_ids	integer[]	Optional	`1` = 2ha, `2` = 50ha
species_groups	string[]	Optional	Filter to specific groups

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/trends?location_ids=2&view_by=species_groups"

Response shape

{
  "data": {
    "tree_density_per_ha": {
      "2017": { "sum": 86.4, "Dipterocarp": 20.1, "Non-dipterocarp": 52.6, /* ... */ },
      "2019": { /* ... */ }
    },
    "volume_per_ha": { /* same structure */ },
    /* basal_area_per_ha, biomass_per_ha, carbon_per_ha ... */
  }
}

GET /v3/species-breakdown Top-N species ranked by metric ▶

Parameters

Example

Name	Type	Required	Description
years	integer[]	Optional	Census year filter
location_ids	integer[]	Optional	`1` or `2`
top_n	integer	Optional	Number of top species to return. Default `5`, max `100`.
species_groups	string[]	Optional	Filter by group

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/species-breakdown?years=2021&location_ids=2&top_n=10"

GET /v3/forecast 30-year DBH class projection ▶

Parameters

Example

Name	Type	Required	Description
location_id	integer	Required	`1` = 2ha, `2` = 50ha
baseline_year	integer	Required	Starting census year for projection, e.g. `2021`
years	integer[]	Optional	Additional historical years to include
species_group	string[]	Optional	Filter to specific groups

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/forecast?location_id=2&baseline_year=2021"

GET /v3/flora Paginated individual tree records ▶

Parameters

Example

Name	Type	Required	Description
years	integer[]	Optional	Census year filter
location_ids	integer[]	Optional	`1` or `2`
species_groups	string[]	Optional	Filter by group
page	integer	Optional	Page number. Default `1`.
page_size	integer	Optional	Records per page. Default `50`, max `200`.

Request

curl "https://cv2nj26jua.execute-api.ap-southeast-1.amazonaws.com/v3/flora?years=2021&location_ids=2&page=1&page_size=20"

Response shape

{
  "data": [ { "tag": "2317", "species_name": "Shorea leprosula", "dbh_cm": 65.3, /* ... */ } ],
  "pagination": { "page": 1, "page_size": 20, "total": 4120, "total_pages": 207, "has_next": true }
}