Статистика индексов

GET /v1/fields/{id}/statistics возвращает по строке статистики на каждую дату со снимком: как индекс вегетации был распределён по пикселям поля в этот день. Это основной запрос для графиков развития посевов, оповещений об аномалиях и сравнения сезонов.

Примеры на Python и JavaScript используют API, session, headers и id поля из быстрого старта.

Запрос

Параметр	Обязателен	Примечание
index	да	Один из индексов ниже.
from	да	Первый день, YYYY-MM-DD.
to	да	Последний день, YYYY-MM-DD, не раньше from и не позже чем через 366 дней.
source	нет	sentinel-2 (по умолчанию) или planet.

curl

curl "https://api.agrosat.uz/v1/fields/cmgz7k2qv0004l8p3a9d1x6rt/statistics?index=ndvi&from=2026-04-01&to=2026-09-30" \
  -H "X-API-Key: $AGROSAT_API_KEY"

Python

r = session.get(
    f"{API}/fields/{field_id}/statistics",
    params={"index": "ndvi", "from": "2026-04-01", "to": "2026-09-30"},
    timeout=120,
)
body = r.json()
usable = [row for row in body["data"]["data"] if row["valid_fraction"] >= 0.8]
for row in usable:
    print(row["date"], round(row["median"], 3))

JavaScript

const url = new URL(`${API}/fields/${fieldId}/statistics`);
url.search = new URLSearchParams({ index: "ndvi", from: "2026-04-01", to: "2026-09-30" });
const body = await (await fetch(url, { headers })).json();
const usable = body.data.data.filter((row) => row.valid_fraction >= 0.8);
for (const row of usable) console.log(row.date, row.median.toFixed(3));

Если поле или окно ещё не подготовлено, придёт ответ 202 data_pending с заголовком Retry-After. Подождите и повторите запрос; см. Готовность поля.

Ответ

{
  "success": true,
  "data": {
    "field_id": "cmgz7k2qv0004l8p3a9d1x6rt",
    "index": "ndvi",
    "data": [
      {
        "date": "2026-05-04",
        "mean": 0.5871, "median": 0.6012, "min": 0.1544, "max": 0.7785,
        "std": 0.0962, "p10": 0.4518, "p90": 0.6973,
        "valid_fraction": 0.9934, "cloud_fraction": 0.0066, "cloud_mask": "scl_cld"
      },
      {
        "date": "2026-05-09",
        "mean": null, "median": null, "min": null, "max": null,
        "std": null, "p10": null, "p90": null,
        "valid_fraction": 0, "cloud_fraction": 1, "cloud_mask": "scl_cld"
      }
    ],
    "unavailable_dates": []
  }
}

Строки упорядочены по дате, от старых к новым. В каждой строке:

Поле ответа	Значение
date	Дата снимка, YYYY-MM-DD.
mean, median	Среднее и медиана индекса по пригодным пикселям поля.
min, max	Наименьшее и наибольшее значение среди пригодных пикселей.
std	Стандартное отклонение: насколько неоднородно поле.
p10, p90	10-й и 90-й процентили. Меньше зависят от случайных пикселей на краю поля, чем min и max.
valid_fraction	Доля пригодных пикселей поля, от 0 до 1.
cloud_fraction	Доля пикселей поля, отмеченных как облака, от 0 до 1, или null, если она неизвестна.
cloud_mask	Только для sentinel-2: использованная маска облаков, scl_cld или scl. См. Маски облаков.

Если в какую-то дату ни один пиксель поля не оказался пригодным, строка всё равно присутствует: все значения null, а valid_fraction равен 0. Это значит, что спутник пролетал, но ничего не увидел, а это не то же самое, что отсутствие пролёта.

В unavailable_dates перечислены даты, для которых снимок есть, но статистику не удалось рассчитать за последние 24 часа. Обычно список пуст; см. Готовность поля.

Фильтруйте по valid_fraction

Если в дату был виден только угол поля, статистика описывает только этот угол. Для анализа динамики оставляйте строки выше подходящего вам порога, например valid_fraction >= 0.8, и опирайтесь на median, а не на mean.

Индексы

index	Название	Формула	Обычный диапазон	Planet
ndvi	Normalized Difference Vegetation Index	(NIR − Red) / (NIR + Red)	от −1 до 1	да
ndre	Normalized Difference Red Edge	(NIR − RedEdge) / (NIR + RedEdge)	от −1 до 1	да
ndmi	Normalized Difference Moisture Index	(NIR − SWIR1) / (NIR + SWIR1)	от −1 до 1	—
msavi	Modified Soil-Adjusted Vegetation Index	(2·NIR + 1 − √((2·NIR + 1)² − 8·(NIR − Red))) / 2	от −1 до 1	да
evi	Enhanced Vegetation Index	2.5·(NIR − Red) / (NIR + 6·Red − 7.5·Blue + 1)	от −1 до 1	да
gndvi	Green NDVI	(NIR − Green) / (NIR + Green)	от −1 до 1	да
rci	Red-edge Chlorophyll Index	NIR / RedEdge − 1	от 0 до 10	да
rendvi	Red-edge NDVI	(RedEdge2 − RedEdge1) / (RedEdge2 + RedEdge1)	от −1 до 1	—
sipi	Structure Insensitive Pigment Index	(NIR − Blue) / (NIR − Red)	от 0 до 2	да
gci	Green Chlorophyll Index	NIR / Green − 1	от 0 до 10	да
ndpi	Normalized Difference Pond Index	(SWIR1 − Green) / (SWIR1 + Green)	от −1 до 1	—

Любое другое значение отклоняется с ошибкой 400 invalid_index.

Источники

• sentinel-2 используется по умолчанию и доступен любой организации.
• planet отдаёт данные PlanetScope и доступен только организациям с отдельным договором на Planet. Без договора запрос завершится ошибкой 403 source_not_enabled. Planet поддерживает индексы, отмеченные в таблице выше; для остальных вернётся 400 invalid_index. В строках Planet нет cloud_mask.

Стоимость

Успешный ответ стоит ceil(area_ha × число_дат / 10) юнитов, но не меньше 1. Каждая строка в data считается возвращённой датой, включая полностью облачные. Для поля из примера площадью 41,53 га 6 дат стоят ceil(41,53 × 6 / 10) = 25 юнитов.

Ответ без строк стоит 0, как и любой ответ 202. Израсходованные юниты приходят в заголовке X-AgroSat-Units. См. Юниты и гектары.

Окна и история

Окно не может быть длиннее 366 дней (400 invalid_date_range) и не может начинаться раньше самой ранней даты, разрешённой договором (400 date_out_of_range).

Что дальше

Маски облаковЧто scl_cld и scl означают для ваших данных.

Изображения индексовПосмотрите, откуда на поле берутся значения.

Справочник APIgetFieldStatistics со всеми параметрами (на английском).