Изображения индексов

GET /v1/fields/{id}/image строит изображение одного индекса по полю на одну дату. Формат выбирайте по задаче:

format	Тип содержимого	Для чего
png (по умолчанию)	image/png	Показ поля на карте. Цветное изображение, прозрачное за пределами поля.
tiff	image/tiff	Собственный анализ. Один канал float32 со значениями индекса, NaN за пределами поля, привязка в WGS84 (EPSG:4326).

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

Запрос

Параметр	Обязателен	Примечание
index	да	Индекс из руководства по статистике.
date	да	YYYY-MM-DD. Берите дату из ответа dates.
format	нет	png (по умолчанию) или tiff.
width	нет	Ширина в пикселях, от 64 до 2048, по умолчанию 512. Высота зависит от формы поля.
source	нет	sentinel-2 (по умолчанию) или planet.

При успехе тело ответа — само изображение. При ошибке — обычный JSON-конверт ошибки с Content-Type: application/json, поэтому проверяйте код ответа, прежде чем сохранять тело.

Границы изображения

Заголовок X-AgroSat-Bounds содержит географические границы изображения в WGS84 в виде west,south,east,north (запад, юг, восток, север):

HTTP/1.1 200 OK
Content-Type: image/png
X-AgroSat-Bounds: 68.552,40.3084,68.560,40.3139
X-AgroSat-Units: 42

Чтобы разместить изображение на карте, растяните его ровно по этим границам.

Скачать PNG

curl

curl -sS -D headers.txt -o ndvi.png \
  "https://api.agrosat.uz/v1/fields/cmgz7k2qv0004l8p3a9d1x6rt/image?index=ndvi&date=2026-05-14&width=1024" \
  -H "X-API-Key: $AGROSAT_API_KEY"
grep -i '^x-agrosat-bounds' headers.txt

Python

r = session.get(
    f"{API}/fields/{field_id}/image",
    params={"index": "ndvi", "date": "2026-05-14", "width": 1024},
    timeout=120,
)
if r.headers["Content-Type"].startswith("application/json"):
    raise RuntimeError(r.json()["error"])
west, south, east, north = map(float, r.headers["X-AgroSat-Bounds"].split(","))
with open("ndvi.png", "wb") as f:
    f.write(r.content)

JavaScript

import { writeFile } from "node:fs/promises";

const url = new URL(`${API}/fields/${fieldId}/image`);
url.search = new URLSearchParams({ index: "ndvi", date: "2026-05-14", width: "1024" });
const res = await fetch(url, { headers });
if (!res.ok || res.status === 202) throw new Error(JSON.stringify(await res.json()));
const [west, south, east, north] = res.headers.get("X-AgroSat-Bounds").split(",").map(Number);
await writeFile("ndvi.png", Buffer.from(await res.arrayBuffer()));

Например, в Leaflet ваш фронтенд показывает PNG вызовом L.imageOverlay(pngUrl, [[south, west], [north, east]]). Отдавайте PNG со своего бэкенда: API-ключ не должен попадать в браузер.

Чтение GeoTIFF

GeoTIFF содержит сами значения индекса, поэтому по нему можно строить собственные зоны, гистограммы или разницу между датами. На Python с rasterio:

import numpy as np
import rasterio
from rasterio.io import MemoryFile

r = session.get(
    f"{API}/fields/{field_id}/image",
    params={"index": "ndvi", "date": "2026-05-14", "format": "tiff", "width": 1024},
    timeout=120,
)
r.raise_for_status()

with MemoryFile(r.content) as memfile, memfile.open() as ds:
    print(ds.crs, ds.bounds, ds.dtypes[0])   # EPSG:4326, прямоугольник X-AgroSat-Bounds, float32
    ndvi = ds.read(1)                         # двумерный массив, NaN за пределами поля

values = ndvi[np.isfinite(ndvi)]
print("пикселей в поле:", values.size)
print("медиана NDVI:", float(np.median(values)))
print("доля ниже 0.3:", float((values < 0.3).mean()))

r.raise_for_status() останавливается и на 202; если поле может быть ещё не готово, обрабатывайте этот ответ, как описано в разделе Готовность поля.

Облака на изображениях

Изображение строится по сцене, которую AgroSat выбрал для этой даты. В отличие от статистики, облачность для изображения не сообщается: прежде чем доверять картинке, проверьте valid_fraction и cloud_fraction на ту же дату в статистике.

Ошибки

Ответ	Когда
404 no_imagery_for_date	Даты нет среди дат снимков поля или снимок нельзя отрисовать.
400 invalid_request	format не png и не tiff, width вне диапазона от 64 до 2048 или date не является корректной датой YYYY-MM-DD.
400 invalid_index	Неизвестный индекс или индекс, который выбранный источник не поддерживает.
202 data_pending	Поле или каталог сцен на эту дату ещё готовится. Бесплатно.

Стоимость

Изображение стоит ceil(area_ha) юнитов, но не меньше 1, независимо от формата и ширины. Для поля из примера площадью 41,53 га одно изображение стоит 42 юнита.

Что дальше

Даты снимковНайдите даты, которые стоит отрисовать.

Юниты и гектарыПланируйте запросы изображений с учётом квоты.