Інструкція з роботи з API

1. З чого почати

Agrotest API передає дані вашого господарства до іншої програми: перелік полів, доступні роки, контури й зони, аналіз ґрунту та рекомендації з внесення добрив. API працює тільки на читання: змінити або видалити дані через нього неможливо.

Для підключення потрібні адреса вашого сайту Agrotest та API-ключ, виданий адміністратором. Логін і пароль від кабінету не замінюють цей ключ.

Перевірити доступність сервісу

curl "https://YOUR_AGROTEST_HOST/api/v1/health"

Для цього запиту ключ не потрібен. Успішна відповідь підтверджує доступність сервісу, але ще не перевіряє ваш ключ або доступ до полів.

2. Ключ та авторизація

Передавайте ключ у заголовку Authorization: Bearer YOUR_API_KEY. У всіх прикладах замініть YOUR_API_KEY на свій ключ, а FIELD_ID, PERIOD_ID, DATASET_ID та FERTILIZER_ID — на числові ID з відповідей API.

curl "https://YOUR_AGROTEST_HOST/api/v1/me" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

/me показує клієнта, до якого прив'язаний ключ. Один ключ — один клієнт. Параметр client_id не передавайте: API визначає клієнта за ключем і відхиляє такий параметр. Застарілий шлях /v1/clients не використовується.

• Отримайте окремий ключ для інтеграції у адміністратора Agrotest.
• Для робочого сервера використовуйте HTTPS. HTTP допустимий лише у довіреному локальному середовищі.
• Не додавайте ключ до URL, Git, скриншотів або публічного JavaScript. Зберігайте його в захищених налаштуваннях вашого сервера.
• Після завершення строку дії або відкликання ключа зверніться до адміністратора. Втрачений ключ потрібно перевипустити.

Приклади команд призначені для термінала з curl та синтаксисом Bash. У Windows PowerShell запускайте curl.exe й записуйте команду в один рядок без символів перенесення \. Власну інтеграцію рекомендовано виконувати на сервері: браузерні запити з іншого домену можуть блокуватися політикою CORS.

3. Поле, період і набір даних

Одне поле може мати кілька наборів навіть у межах одного періоду. Порівнюйте analysis_date та прапорці has_boundary, has_zones, has_soil_analysis, has_recommendations. Вони показують наявність відповідних шарів, але не гарантують значення кожного показника в кожній зоні.

Для геометрії, аналізу та рекомендацій завжди потрібен явний dataset_id. Він має належати саме обраному полю. API не змішує різні набори автоматично.

4. Приклад: знайти «Поле 6» і потрібний рік

Крок 1. Отримати доступні періоди

curl "https://YOUR_AGROTEST_HOST/api/v1/periods?has_fields=true&page=1&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Знайдіть потрібну назву або значення year і запам'ятайте її id. Для складених назв періоду значення year може бути null.

Крок 2. Знайти поле за назвою або номером

curl -G "https://YOUR_AGROTEST_HOST/api/v1/fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "search=Поле 6" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=25"

Перевірте name, number і region: однакова назва може бути у різних полів. Візьміть id потрібного запису як FIELD_ID. Масив available_periods показує його доступні періоди. За потреби додайте region_id та period_id до фільтрів.

Крок 3. Отримати набори цього поля

curl "https://YOUR_AGROTEST_HOST/api/v1/fields/FIELD_ID/datasets?period_id=PERIOD_ID&page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Виберіть запис за датою аналізу та візьміть його id як DATASET_ID. Якщо потрібні всі набори поля, приберіть параметр period_id. Перегляньте всі сторінки, якщо meta.total_pages більше 1.

Крок 4. Перевірити картку поля

curl "https://YOUR_AGROTEST_HOST/api/v1/fields/FIELD_ID?dataset_id=DATASET_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Без dataset_id картка вибирає набір автоматично лише тоді, коли після фільтрації він один. Якщо наборів кілька, повертається meta.dataset_selection: "ambiguous": оберіть потрібний набір зі списку.

5. Геометрія та аналіз ґрунту

Контур поля

curl "https://YOUR_AGROTEST_HOST/api/v1/fields/FIELD_ID/geometry?dataset_id=DATASET_ID&layer=boundary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Параметр layer приймає boundary (контур), grid (сітка), zones (зони) або all (усі шари). Відповідь — GeoJSON FeatureCollection, без зовнішнього блоку data. Координати WGS84 записані як [довгота, широта]. Для зон враховуйте пагінацію.

Значення показників за зонами

curl "https://YOUR_AGROTEST_HOST/api/v1/fields/FIELD_ID/soil-analysis?dataset_id=DATASET_ID&indicators=ph_h2o,phosphorus,potassium&include_geometry=false&page=1&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Публічні коди показників беріть із /dictionaries/indicators?type=analysis. Коди передаються через кому. Якщо не вказувати indicators, API поверне всі доступні показники аналізу. Внутрішні назви колонок бази даних не приймаються.

include_geometry=true додає геометрію до кожної зони, але збільшує розмір відповіді. Одиниці вимірювання читайте в values і довіднику показників — не вважайте всі значення відсотками або кг/га.

6. Рекомендації та добрива

Спочатку отримайте коди діючих речовин:

curl "https://YOUR_AGROTEST_HOST/api/v1/dictionaries/indicators?type=recommendation&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Замініть NUTRIENT_CODE на код із цього довідника. Коди для рекомендацій можуть відрізнятися від кодів аналізу ґрунту.

curl "https://YOUR_AGROTEST_HOST/api/v1/fields/FIELD_ID/recommendations?dataset_id=DATASET_ID&nutrient_code=NUTRIENT_CODE&page=1&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Без fertilizer_id повертаються дози діючої речовини. Щоб перерахувати їх на конкретне добриво, отримайте сумісні добрива через /dictionaries/fertilizers?nutrient_code=NUTRIENT_CODE і додайте &fertilizer_id=FERTILIZER_ID до запиту рекомендацій.

• nutrient_rate — доза діючої речовини для зони.
• fertilizer_rate — доза з урахуванням коефіцієнта обраного добрива; без добрива коефіцієнт дорівнює 1.
• amount_kg — кількість для площі конкретної зони, якщо площа відома.
• summary — підсумок для всього набору, а не лише поточної сторінки зон. Не додавайте його повторно для кожної сторінки.

Якщо площі зон відсутні, деякі підсумки можуть бути null, а meta.warnings міститиме ZONE_AREA_MISSING. Якщо не передати nutrient_code, він вибирається автоматично лише за наявності однієї речовини з даними; кілька речовин дають відповідь 409 AMBIGUOUS_NUTRIENT.

7. Усі методи API v1

Усі методи нижче використовують GET; шляхи вказані відносно /api/v1. Крім /health, потрібен Bearer-ключ.

Для областей і періодів has_fields=true задано за замовчуванням. Значення false лише прибирає вимогу наявності базового набору, але не відкриває чужі дані. Список полів типово містить лише активні поля з базовим набором за вказаний період.

8. Як читати відповідь і завантажити всі сторінки

Звичайний успішний запит повертає код 200. Дані знаходяться в data, службова інформація — в meta. Для списків data є масивом, для картки — об'єктом. Геометрія та перевірка /health мають власний формат відповіді.

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "total_pages": 0,
    "request_id": "req_EXAMPLE"
  }
}

Це приклад успішного запиту без знайдених записів. data: [] — не помилка сервера. Перевірте ID періоду, область, статус поля та клієнта у /me. Спробуйте прибрати необов'язкові фільтри.

1. Почніть з page=1.
2. Обробіть записи поточної сторінки.
3. Збільшуйте page, доки він не досягне meta.total_pages. Для порожнього списку сторінок немає.

Типовий розмір сторінки — 25, максимум для звичайних списків — 100. Для геометрії зон, а також аналізу й рекомендацій з include_geometry=true, типовий максимальний розмір — 1000. У відповідях із зонами використовується meta.total_zones замість meta.total. Довідник одиниць повертається повністю.

Типове обмеження — 60 запитів за хвилину на ключ. Орієнтуйтеся на X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset: налаштування сервера можуть відрізнятися. Після 429 зачекайте кількість секунд із Retry-After, не повторюйте запит у безперервному циклі.

9. Коди відповіді та вирішення помилок

Статус стосується конкретного виконаного запиту. Перелік кодів у документації показує можливі ситуації, а не означає, що всі ці помилки виникли одночасно.

Код 402 у поточному контракті Agrotest API не використовується. Не визначайте причину помилки лише за припущенням про версію бази даних — для діагностики потрібен request_id.

10. Як користуватися Swagger

1. Відкрийте Swagger на цьому сайті.
2. Натисніть Authorize, введіть лише сам ключ без префікса Bearer і підтвердьте. Swagger додасть префікс сам.
3. Розкрийте метод, за потреби натисніть Try it out та заповніть параметри. Необов'язкові фільтри можна залишити порожніми.
4. Натисніть Execute. У Request URL перевірте адресу і параметри.
5. Читайте Server response → Code / Response body: це реальний результат запиту.
6. Блок Responses → Example Value / Schema нижче — лише приклад формату й опис полів. Числа та назви в ньому не є результатом вашого запиту.

Якщо Swagger недоступний, адміністратор міг вимкнути інтерактивну документацію. Це не обов'язково означає, що саме API не працює: перевірте /api/v1/health та уточніть налаштування доступу.