added land

API.md

@@ -7,9 +7,9 @@
 
 ## Состояние Реализации
 
-- Работает: healthcheck, OpenAPI, DEM elevation/profile, OSM buildings query, terrain LOS/Fresnel/diffraction с учётом DEM и buildings, manual link budget, antenna sector/beam helpers.
+- Работает: healthcheck, OpenAPI, DEM elevation/profile, OSM buildings query, landcover/canopy path sampling, terrain LOS/Fresnel/diffraction с учётом DEM и buildings, manual link budget, antenna sector/beam helpers.
 - Частично работает: coverage/viewshed создают job-stub, но тяжёлый расчёт ещё не реализован.
-- Пока не реализовано: landcover/canopy sampling, vegetation attenuation по реальным данным, ITM/P.1812/P.452/P.676, реальные async results для coverage/viewshed.
+- Пока не реализовано: vegetation attenuation по реальным данным, ITM/P.1812/P.452/P.676, реальные async results для coverage/viewshed.
 
 ## Общие Правила
 
@@ -309,18 +309,49 @@ curl -s -X POST http://localhost:5603/api/v1/antenna/beam \
 
 ### `POST /api/v1/landcover/path`
 
-Контракт есть, но raster sampling landcover/canopy пока не реализован. Сейчас endpoint возвращает `501 Not Implemented`.
+Сэмплит landcover raster вдоль трассы и сворачивает точки в сегменты.
+Canopy raster используется опционально: если файлов нет, endpoint всё равно
+работает, но `canopy_height_m` будет `null`.
+
+Ожидаемые данные:
+
+- `LANDCOVER_PATH`: GeoTIFF/COG с кодами ESA WorldCover.
+- `CANOPY_PATH`: GeoTIFF/COG с высотой кроны в метрах.
+
+Поддерживаемые классы ESA WorldCover:
+
+- `10`: `tree_cover`
+- `20`: `shrubland`
+- `30`: `grassland`
+- `40`: `cropland`
+- `50`: `built_up`
+- `60`: `bare_sparse_vegetation`
+- `70`: `snow_ice`
+- `80`: `water`
+- `90`: `herbaceous_wetland`
+- `95`: `mangroves`
+- `100`: `moss_lichen`
 
 ```bash
-curl -i -X POST http://localhost:5603/api/v1/landcover/path \
+curl -s -X POST http://localhost:5603/api/v1/landcover/path \
   -H 'Content-Type: application/json' \
   -d '{
     "start": {"lat": 59.935, "lon": 30.305},
     "end": {"lat": 59.945, "lon": 30.325},
     "samples": 256
-  }'
+  }' | jq
 ```
 
+Ключевые поля ответа:
+
+- `segments`: участки с одинаковым landcover class.
+- `segments[].class`: класс покрова.
+- `segments[].forest_type`: пока `unknown` для `tree_cover`/`mangroves`, `null` для остальных классов.
+- `segments[].canopy_height_m`: средняя высота кроны на сегменте, если canopy raster доступен.
+- `vegetation_depth_m`: суммарная длина участков `tree_cover`/`mangroves` по трассе.
+
+Если landcover raster отсутствует или не покрывает трассу, endpoint возвращает `501 Not Implemented`.
+
 ## Viewshed
 
 ### `POST /api/v1/viewshed`