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

Полное руководство по API сети Meshtastic Самара. Получайте доступ к живым данным mesh-сети, создавайте интеграции и приложения.

🚀 Быстрый старт

Базовый URL

Продакшн:
https://meshtastic-samara.ru/api
Разработка:
http://localhost:3000/api

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

✅ Публичный доступ
Большинство endpoints доступны публично
🔑 API ключи
Требуются для операций записи (скоро)

📖 Интерактивная документация

Изучайте API интерактивно с помощью Swagger UI. Тестируйте endpoints, просматривайте схемы и понимайте структуры данных.

Открыть интерактивную документацию API

🔗 API Endpoints

Система

  • GET /health
    Проверка состояния системы
  • GET /status
    Статус системы и настройка
  • GET /mqtt
    Статус MQTT сервиса
  • POST /mqtt
    Запуск MQTT сервиса
  • GET /startup
    Инициализация сервисов

Сеть

  • GET /nodes
    Активные узлы mesh-сети
  • GET /neighbours
    Топология сети
  • GET /traceroutes
    Трассировка сетевых путей
  • GET /map-reports
    Отчеты карты узлов

Связь

  • GET /messages
    Последние сообщения
  • GET /waypoints
    Путевые точки

Аналитика

  • GET /network-stats
    Детальная статистика сети
  • GET /stats
    Базовая статистика
  • GET /hardware-stats
    Статистика устройств

Карта

  • GET /buildings
    Данные зданий для карты

Документация

  • GET /openapi.json
    API спецификация (JSON)
  • GET /openapi.yaml
    API спецификация (YAML)

💻 Примеры кода

JavaScript/TypeScript

// Get active nodes with filtering
const response = await fetch('https://meshtastic-samara.ru/api/nodes?online_only=true&limit=10');
const data = await response.json();

console.log(`Found ${data.count} active nodes`);
data.nodes.forEach(node => {
  console.log(`${node.longName} - ${node.isOnline ? 'Online' : 'Offline'}`);
});

// Get recent messages with city filtering
const messagesResponse = await fetch('https://meshtastic-samara.ru/api/messages?limit=10&city=Самара');
const messagesData = await messagesResponse.json();

messagesData.messages.forEach(message => {
  console.log(`${message.fromName}: ${message.text}`);
});

// Get network statistics
const statsResponse = await fetch('https://meshtastic-samara.ru/api/network-stats');
const statsData = await statsResponse.json();

console.log(`Network uptime: ${statsData.networkUptime}%`);
console.log(`Messages in last 24h: ${statsData.messagesLast24h}`);

// Get hardware statistics
const hardwareResponse = await fetch('https://meshtastic-samara.ru/api/hardware-stats');
const hardwareData = await hardwareResponse.json();

console.log(`Total devices: ${hardwareData.totalDevices}`);
console.log(`Most popular: ${hardwareData.mostPopular?.name}`);

Python

import requests
import json

# Get active nodes with filtering
response = requests.get('https://meshtastic-samara.ru/api/nodes?online_only=true&limit=10')
data = response.json()

print(f"Found {data['count']} active nodes")
for node in data['nodes']:
    status = "Online" if node['isOnline'] else "Offline"
    print(f"{node['longName']} - {status}")

# Get recent messages with city filtering
messages_response = requests.get('https://meshtastic-samara.ru/api/messages?limit=10&city=Самара')
messages_data = messages_response.json()

for message in messages_data['messages']:
    print(f"{message['fromName']}: {message['text']}")

# Get detailed network statistics
stats_response = requests.get('https://meshtastic-samara.ru/api/network-stats')
stats_data = stats_response.json()

print(f"Network uptime: {stats_data['networkUptime']}%")
print(f"Messages in last 24h: {stats_data['messagesLast24h']}")

# Get hardware statistics
hardware_response = requests.get('https://meshtastic-samara.ru/api/hardware-stats')
hardware_data = hardware_response.json()

print(f"Total devices: {hardware_data['totalDevices']}")
if hardware_data['mostPopular']:
    print(f"Most popular device: {hardware_data['mostPopular']['name']}")

# Get buildings for map rendering
buildings_response = requests.get('https://meshtastic-samara.ru/api/buildings?bounds=50.0,53.0,50.5,53.5&limit=100')
buildings_data = buildings_response.json()

print(f"Found {buildings_data['count']} buildings in area")

cURL

# Get active nodes with filtering
curl -X GET "https://meshtastic-samara.ru/api/nodes?online_only=true&limit=10" \
     -H "Accept: application/json"

# Get recent messages with city filtering
curl -X GET "https://meshtastic-samara.ru/api/messages?limit=20&city=Самара" \
     -H "Accept: application/json"

# Get detailed network statistics
curl -X GET "https://meshtastic-samara.ru/api/network-stats" \
     -H "Accept: application/json"

# Get hardware statistics
curl -X GET "https://meshtastic-samara.ru/api/hardware-stats" \
     -H "Accept: application/json"

# Get buildings for map rendering
curl -X GET "https://meshtastic-samara.ru/api/buildings?bounds=50.0,53.0,50.5,53.5&limit=100" \
     -H "Accept: application/json"

# Get network topology data
curl -X GET "https://meshtastic-samara.ru/api/neighbours" \
     -H "Accept: application/json"

# Get traceroute data
curl -X GET "https://meshtastic-samara.ru/api/traceroutes" \
     -H "Accept: application/json"

# Start MQTT service
curl -X POST "https://meshtastic-samara.ru/api/mqtt" \
     -H "Accept: application/json"

# Check system health
curl -X GET "https://meshtastic-samara.ru/api/health" \
     -H "Accept: application/json"

⚡ Ограничения скорости

Публичный доступ

100 запросов/минуту
Подходит для большинства приложений и тестирования

Аутентифицированный доступ

1000 запросов/минуту
Для продакшн приложений (скоро)

⚙️ Параметры API

Фильтрация узлов (/nodes)

GET /api/nodes?online_only=true&limit=50

Параметры:
- online_only (boolean): Показать только онлайн узлы
- limit (integer): Максимальное количество узлов

Фильтрация сообщений (/messages)

GET /api/messages?limit=20&channel=0&city=Самара

Параметры:
- limit (integer): Максимальное количество сообщений
- channel (integer): Фильтр по номеру канала
- city (string): Фильтр по городу отправителя

Данные зданий (/buildings)

GET /api/buildings?bounds=50.0,53.0,50.5,53.5&limit=500

Параметры:
- bounds (string): Границы области (запад,юг,восток,север)
- limit (integer): Максимальное количество зданий

📊 Форматы данных

Формат ответа

Все ответы API следуют единому JSON формату с секциями метаданных и данных.

{
  "nodes": [...],           // Array of data objects
  "count": 25,              // Number of items returned
  "lastUpdate": "2024-01-15T10:30:00Z",  // Timestamp
  "source": "live-mqtt",    // Data source
  "success": true           // Success indicator
}

Формат ошибки

{
  "error": "Неверный запрос",
  "code": "INVALID_PARAMETER",
  "details": {
    "parameter": "limit",
    "expected": "целое число от 1 до 1000"
  }
}

🆘 Поддержка и сообщество

Получить помощь

Внести вклад