Готовность поля и подготовка данных

AgroSat ничего не считает, пока поле не зарегистрировано. Регистрация запускает фоновую задачу, которая находит снимки над полем и рассчитывает статистику. Пока эта работа не закончена, запросы данных отвечают 202 data_pending, а не держат соединение открытым.

Что готовится при регистрации

Регистрация готовит историю с 1 января прошлого календарного года по день регистрации. Для поля, зарегистрированного в мае 2026 года, история готовится с 1 января 2025 года.

Если в договоре указана более поздняя самая ранняя дата истории, подготовка начинается с неё.

Статус поля

GET /v1/fields/{id} показывает, в каком состоянии поле:

`status`	Значение
`pending`	История с момента регистрации ещё готовится. Запросы данных отвечают `202`.
`ready`	История с момента регистрации готова.

Если границу готового поля перерисовать в веб-приложении AgroSat, оно снова переходит в pending, пока история не будет подготовлена заново для новой границы.

202 data_pending

Спутниковые эндпоинты отвечают 202, когда запрошенные данные ещё не готовы, и запускают их подготовку, если она ещё не идёт. Тело ответа — конверт ошибки с кодом data_pending, а заголовок Retry-After сообщает, сколько секунд подождать:

HTTP/1.1 202 Accepted
Retry-After: 30
Content-Type: application/json

{"success": false, "error": {"code": "data_pending", "message": "Statistics for this window are being prepared."}}

Ответ 202 приходит, когда:

поле ещё в статусе pending;
вы запрашиваете окно старше истории, подготовленной при регистрации, но в пределах, разрешённых договором;
каталог сцен для окна ещё заполняется;
статистика для части дат окна ещё не рассчитана.

Ориентируйтесь на Retry-After, а не на фиксированную задержку. Простой цикл ожидания:

url="https://api.agrosat.uz/v1/fields/$FIELD_ID/statistics?index=ndvi&from=2025-04-01&to=2025-09-30"
while :; do
  code=$(curl -s -o body.json -D headers.txt -w '%{http_code}' "$url" -H "X-API-Key: $AGROSAT_API_KEY")
  [ "$code" != "202" ] && break
  sleep "$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')"
done
cat body.json

import time

def get_when_ready(session, url, params, max_wait=1800):
    waited = 0
    while True:
        r = session.get(url, params=params, timeout=120)
        if r.status_code != 202:
            return r
        delay = int(r.headers.get("Retry-After", "30"))
        if waited + delay > max_wait:
            raise TimeoutError("данные всё ещё готовятся")
        time.sleep(delay)
        waited += delay

async function getWhenReady(url, headers, maxWaitSeconds = 1800) {
  let waited = 0;
  for (;;) {
    const res = await fetch(url, { headers });
    if (res.status !== 202) return res;
    const delay = Number(res.headers.get("Retry-After") ?? 30);
    if (waited + delay > maxWaitSeconds) throw new Error("данные всё ещё готовятся");
    await new Promise((resolve) => setTimeout(resolve, delay * 1000));
    waited += delay;
  }
}

Если вы регистрируете много полей сразу, опрашивайте GET /v1/fields/{id} (бесплатно), пока каждое не станет ready, а не повторяйте спутниковые запросы в плотном цикле. Оба вида запросов учитываются в лимите частоты.

Насколько далеко в прошлое

Договор задаёт самую раннюю дату, которую может запрашивать ваша организация. Окно, которое начинается раньше, отклоняется, а не готовится:

{
  "success": false,
  "error": {
    "code": "date_out_of_range",
    "message": "The earliest date available to this organization is 2024-01-01."
  }
}

Окна между этой датой и началом истории, подготовленной при регистрации, готовятся при первом запросе: в первый раз ожидайте 202.

Даты, для которых не удалось рассчитать статистику

Бывает, что снимок на дату есть, а статистику по нему рассчитать не удаётся. Если подготовка окна завершилась в последние 24 часа и каких-то дат всё ещё не хватает, API не запускает её повторно. Он отвечает 200 с теми датами, что есть, а остальные перечисляет в unavailable_dates:

{
  "success": true,
  "data": {
    "field_id": "cmgz7k2qv0004l8p3a9d1x6rt",
    "index": "ndvi",
    "data": [
      {
        "date": "2026-05-14",
        "mean": 0.6124, "median": 0.6347, "min": 0.1812, "max": 0.8021,
        "std": 0.0938, "p10": 0.4783, "p90": 0.7214,
        "valid_fraction": 0.9871, "cloud_fraction": 0.0129, "cloud_mask": "scl_cld"
      }
    ],
    "unavailable_dates": ["2026-05-19", "2026-05-24"]
  }
}

Оплачиваются только даты, вернувшиеся в data; ответ без данных бесплатен. Через 24 часа тот же запрос ещё раз попробует рассчитать эти даты.

Что дальше

Статистика индексовПолучите статистику, когда поле готово.

ОшибкиВсе коды ошибок и что с ними делать.