API документация

REST API для интеграции с системой учета зеленых насаждений EcoTree Passport

REST API

Стандартный RESTful API с JSON форматом

OAuth 2.0

Безопасная аутентификация через токены

Rate Limit

1000 запросов в час на ключ

Начало работы

1. Получение API ключа

Для доступа к API необходимо зарегистрироваться и получить API ключ в личном кабинете. После регистрации вы получите:

API_KEY - ваш уникальный ключ доступа
API_SECRET - секретный ключ для подписи запросов

2. Базовый URL

https://api.ecotree-passport.kg/v1

3. Аутентификация

Все запросы требуют заголовок авторизации:

Authorization: Bearer YOUR_API_KEY

Основные эндпоинты

GET/trees

Получить список всех деревьев

Параметры:

pageinteger- Номер страницы (по умолчанию: 1)

limitinteger- Количество записей на странице (по умолчанию: 20)

speciesstring- Фильтр по виду дерева

conditionstring- Фильтр по состоянию (excellent, good, satisfactory, poor, critical)

districtstring- Фильтр по району города

Пример ответа:

{
  "data": [
    {
      "id": "tree_001",
      "passportNumber": "OSH-2024-001",
      "speciesId": "oak_001",
      "location": {
        "lat": 40.5283,
        "lng": 72.7985,
        "address": "ул. Ленина, 45"
      },
      "condition": "excellent",
      "age": 85,
      "height": 18.5,
      "diameter": 62,
      "plantedDate": "1939-05-15",
      "qrCode": "https://api.ecotree-passport.kg/qr/OSH-2024-001"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5247,
    "pages": 263
  }
}

GET/trees/{id}

Получить детальную информацию о конкретном дереве

Параметры:

idstring- Уникальный идентификатор дерева

Пример ответа:

{
  "id": "tree_001",
  "passportNumber": "OSH-2024-001",
  "speciesId": "oak_001",
  "location": {
    "lat": 40.5283,
    "lng": 72.7985,
    "address": "ул. Ленина, 45",
    "district": "Центральный"
  },
  "condition": "excellent",
  "age": 85,
  "height": 18.5,
  "diameter": 62,
  "crownDiameter": 12.3,
  "plantedDate": "1939-05-15",
  "lastInspection": "2024-08-15",
  "images": [
    "https://cdn.ecotree-passport.kg/trees/tree_001_01.jpg"
  ],
  "qrCode": "https://api.ecotree-passport.kg/qr/OSH-2024-001",
  "notes": "Историческое дерево, охраняется государством"
}

GET/species

Получить список всех видов деревьев в каталоге

Параметры:

familystring- Фильтр по семейству

searchstring- Поиск по названию

Пример ответа:

{
  "data": [
    {
      "id": "oak_001",
      "name": "Дуб черешчатый",
      "scientificName": "Quercus robur",
      "family": "Буковые",
      "description": "Мощное лиственное дерево высотой до 40 метров",
      "lifespan": "300-500 лет",
      "growthRate": "Медленный",
      "count": 847,
      "image": "https://cdn.ecotree-passport.kg/species/oak.jpg"
    }
  ]
}

POST/reports

Создать отчет о проблеме с деревом

Параметры:

treeIdstringобязательный- ID дерева

typestringобязательный- Тип проблемы (disease, damage, illegal_cutting, other)

descriptionstringобязательный- Описание проблемы

reporterNamestring- Имя отправителя

reporterContactstring- Контакт отправителя

imagesarray- Массив URL изображений

Пример ответа:

{
  "id": "report_534",
  "treeId": "tree_001",
  "type": "damage",
  "description": "Обнаружено повреждение коры",
  "status": "new",
  "createdAt": "2024-12-12T10:30:00Z",
  "message": "Отчет успешно создан и принят в обработку"
}

GET/analytics/statistics

Получить общую статистику по деревьям

Пример ответа:

{
  "totalTrees": 5247,
  "totalSpecies": 127,
  "byCondition": {
    "excellent": 1847,
    "good": 2134,
    "satisfactory": 891,
    "poor": 287,
    "critical": 88
  },
  "byDistrict": {
    "Центральный": 1523,
    "Северный": 1098,
    "Восточный": 1345,
    "Южный": 1281
  },
  "recentReports": 892,
  "lastUpdate": "2024-12-12T08:00:00Z"
}

Коды ошибок

Код	Описание	Решение
`400`	Bad Request - Неверный формат запроса	Проверьте параметры запроса
`401`	Unauthorized - Отсутствует авторизация	Добавьте заголовок Authorization с API ключом
`403`	Forbidden - Доступ запрещен	Проверьте права доступа
`404`	Not Found - Ресурс не найден	Проверьте правильность URL
`429`	Too Many Requests - Превышен лимит запросов	Подождите перед следующим запросом
`500`	Internal Server Error - Ошибка сервера	Повторите запрос позже или обратитесь в поддержку

SDK и библиотеки

Официальные SDK для быстрой интеграции с EcoTree Passport API

JavaScript / TypeScript

v1.2.0

Python

v1.1.5

PHP

v1.0.8

v1.0.3