LichessStatTgWeb/LichessWebServices/API_DOCUMENTATION.md

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

Описание

Lichess Statistics API предоставляет REST API для получения детальной статистики игроков платформы Lichess. API позволяет получать информацию о играх, рейтингах и решении задач (пазлов) за различные периоды времени.

Возможности

• 📊 Статистика игр по режимам (Bullet, Blitz, Rapid)
• 🧩 Статистика решения задач (пазлов)
• 📅 Статистика за разные периоды (сегодня, вчера, неделя)
• 🎯 Отслеживание изменений рейтинга
• 📈 Подробная аналитика результатов игр

Режимы игр

• Bullet: Быстрые игры (1-3 минуты)
• Blitz: Блиц игры (3-10 минут)
• Rapid: Рапид игры (10+ минут)

Базовый URL

http://localhost:8001

Эндпоинты

1. Информация об API

GET /

Возвращает основную информацию об API и доступных эндпоинтах.

Ответ:

{
  "message": "Lichess Statistics API",
  "version": "1.0.0",
  "description": "REST API для получения статистики игроков Lichess",
  "endpoints": {
    "today": "/stats/{username}/today",
    "yesterday": "/stats/{username}/yesterday",
    "week": "/stats/{username}/week"
  },
  "documentation": "/docs",
  "openapi_schema": "/openapi.json"
}

2. Health Check

GET /health

Проверка состояния сервиса.

Ответ:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "service": "Lichess Statistics API"
}

3. Статистика за сегодня

GET /stats/{username}/today

Получает статистику игрока за сегодняшний день.

Параметры:

• username (string, обязательный) - имя пользователя на Lichess

Пример запроса:

curl http://localhost:8001/stats/magnus/today

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

{
  "message": "Статистика за сегодняшний день",
  "data": {
    "username": "magnus",
    "tasks": {
      "total": 15,
      "solved": 12,
      "unsolved": 3
    },
    "games": {
      "bullet": {
        "games_played": 8,
        "rating_change": 15,
        "final_rating": 2850,
        "wins": 5,
        "losses": 2,
        "draws": 1
      },
      "blitz": {
        "games_played": 3,
        "rating_change": -5,
        "final_rating": 2750,
        "wins": 1,
        "losses": 2,
        "draws": 0
      },
      "rapid": {
        "games_played": 0,
        "rating_change": 0,
        "final_rating": 0,
        "wins": 0,
        "losses": 0,
        "draws": 0
      }
    }
  }
}

4. Статистика за вчера

GET /stats/{username}/yesterday

Получает статистику игрока за вчерашний день.

Параметры:

• username (string, обязательный) - имя пользователя на Lichess

Пример запроса:

curl http://localhost:8001/stats/magnus/yesterday

5. Статистика за неделю

GET /stats/{username}/week

Получает агрегированную статистику игрока за последние 7 дней.

Параметры:

• username (string, обязательный) - имя пользователя на Lichess

Пример запроса:

curl http://localhost:8001/stats/magnus/week

6. Статистика игр за период

GET /games/{username}/period

Получает детальную статистику игр пользователя за указанный период времени.

Параметры:

• username (string, обязательный) - имя пользователя на Lichess
• since (integer, обязательный) - начало периода (Unix timestamp в миллисекундах)
• until (integer, обязательный) - конец периода (Unix timestamp в миллисекундах)
• rated_only (boolean, опциональный) - только рейтинговые игры (по умолчанию true - рекомендуется)

Пример запроса:

# Статистика за последние 7 дней
curl "http://localhost:8001/games/magnus/period?since=1640995200000&until=1641081600000"

# Только рейтинговые игры
curl "http://localhost:8001/games/magnus/period?since=1640995200000&until=1641081600000&rated_only=true"

# Все игры (включая нерейтинговые)
curl "http://localhost:8001/games/magnus/period?since=1640995200000&until=1641081600000&rated_only=false"

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

{
  "message": "Статистика игр за период",
  "username": "magnus",
  "period_start": 1640995200000,
  "period_end": 1641081600000,
  "games_count": 25,
  "data": {
    "bullet": {
      "games_played": 10,
      "wins": 6,
      "losses": 3,
      "draws": 1,
      "rating_change": 15
    },
    "blitz": {
      "games_played": 8,
      "wins": 5,
      "losses": 2,
      "draws": 1,
      "rating_change": 12
    },
    "rapid": {
      "games_played": 5,
      "wins": 3,
      "losses": 1,
      "draws": 1,
      "rating_change": 8
    },
    "classical": {
      "games_played": 2,
      "wins": 1,
      "losses": 1,
      "draws": 0,
      "rating_change": 0
    },
    "correspondence": {
      "games_played": 0,
      "wins": 0,
      "losses": 0,
      "draws": 0,
      "rating_change": 0
    },
    "total": {
      "games_played": 25,
      "wins": 15,
      "losses": 7,
      "draws": 3,
      "rating_change": 35
    }
  }
}

7. Статистика решения задач за период

GET /puzzle/period

Получает статистику решения задач (пазлов) за указанный период времени. Требует авторизации через Bearer токен.

Параметры:

• since (integer, обязательный) - начало периода (Unix timestamp в миллисекундах)
• until (integer, обязательный) - конец периода (Unix timestamp в миллисекундах)
• max (integer, опциональный) - максимальное количество задач для получения (по умолчанию 50, максимум 1000)
• Authorization (header, обязательный) - Bearer токен авторизации

Важно: Параметр max ограничивает количество активностей, получаемых от Lichess API. Если в указанном периоде было больше задач, чем указано в max, то будут показаны только последние N активностей. Для получения полной статистики рекомендуется увеличить значение max или использовать значение по умолчанию (50).

Пример запроса:

# Статистика за последние 7 дней
curl -H "Authorization: Bearer your_token_here" \
     "http://localhost:8001/puzzle/period?since=1640995200000&until=1641081600000"

# Больше задач
curl -H "Authorization: Bearer your_token_here" \
     "http://localhost:8001/puzzle/period?since=1640995200000&until=1641081600000&max=100"

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

{
  "message": "Статистика решения задач за период",
  "period_start": 1640995200000,
  "period_end": 1641081600000,
  "max_puzzles": 50,
  "puzzles_in_period": 15,
  "data": {
    "total_attempts": 15,
    "solved": 12,
    "failed": 3,
    "success_rate": 80.0
  }
}

Получение токена:

1. Зайдите на https://lichess.org/account/oauth/token/create
2. Создайте новый токен с правами на чтение активности
3. Используйте токен в заголовке Authorization

Модели данных

TaskStats

Статистика решения задач (пазлов):

{
  "total": 15,      // Общее количество решенных задач
  "solved": 12,     // Количество правильно решенных задач
  "unsolved": 3     // Количество нерешенных или неправильно решенных задач
}

GameModeStats

Статистика игр для конкретного режима:

{
  "games_played": 8,    // Общее количество сыгранных игр
  "rating_change": 15,  // Изменение рейтинга (может быть отрицательным)
  "final_rating": 2850, // Текущий рейтинг игрока
  "wins": 5,           // Количество побед
  "losses": 2,         // Количество поражений
  "draws": 1           // Количество ничьих
}

GamesStats

Статистика игр по всем режимам:

{
  "bullet": { /* GameModeStats */ },
  "blitz": { /* GameModeStats */ },
  "rapid": { /* GameModeStats */ }
}

UserStats

Полная статистика пользователя:

{
  "username": "magnus",
  "tasks": { /* TaskStats */ },
  "games": { /* GamesStats */ }
}

ActivityResponse

Ответ API с результатами запроса:

{
  "message": "Статистика за сегодняшний день",
  "data": { /* UserStats или null */ }
}

Коды ошибок

• 200 - Успешный запрос
• 404 - Пользователь не найден или неактивен
• 500 - Внутренняя ошибка сервера

Примеры ошибок

Пользователь не найден

{
  "message": "Пользователь magnus не найден или неактивен"
}

Внутренняя ошибка сервера

{
  "detail": "Внутренняя ошибка сервера: Connection timeout"
}

Swagger UI

Интерактивная документация доступна по адресу:

http://localhost:8001/docs

OpenAPI Schema

Схема OpenAPI доступна по адресу:

http://localhost:8001/openapi.json

Запуск в Docker

# Сборка и запуск
docker compose up --build -d

# Проверка статуса
docker compose ps

# Просмотр логов
docker compose logs

# Остановка
docker compose down

Разработка

Установка зависимостей

pip install -r requirements.txt

Запуск в режиме разработки

uvicorn main:app --host 0.0.0.0 --port 8001 --reload

Лицензия

MIT License