389 lines
11 KiB
Markdown
389 lines
11 KiB
Markdown
|
# 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 и доступных эндпоинтах.
|
|||
|
|
|
|||
|
|
**Ответ:**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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
|
|||
|
|
Проверка состояния сервиса.
|
|||
|
|
|
|||
|
|
**Ответ:**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"status": "healthy",
|
|||
|
|
"timestamp": "2024-01-15T10:30:00Z",
|
|||
|
|
"service": "Lichess Statistics API"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. Статистика за сегодня
|
|||
|
|
|
|||
|
|
#### GET /stats/{username}/today
|
|||
|
|
Получает статистику игрока за сегодняшний день.
|
|||
|
|
|
|||
|
|
**Параметры:**
|
|||
|
|
- `username` (string, обязательный) - имя пользователя на Lichess
|
|||
|
|
|
|||
|
|
**Пример запроса:**
|
|||
|
|
```bash
|
|||
|
|
curl http://localhost:8001/stats/magnus/today
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Пример ответа:**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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
|
|||
|
|
|
|||
|
|
**Пример запроса:**
|
|||
|
|
```bash
|
|||
|
|
curl http://localhost:8001/stats/magnus/yesterday
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5. Статистика за неделю
|
|||
|
|
|
|||
|
|
#### GET /stats/{username}/week
|
|||
|
|
Получает агрегированную статистику игрока за последние 7 дней.
|
|||
|
|
|
|||
|
|
**Параметры:**
|
|||
|
|
- `username` (string, обязательный) - имя пользователя на Lichess
|
|||
|
|
|
|||
|
|
**Пример запроса:**
|
|||
|
|
```bash
|
|||
|
|
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 - рекомендуется)
|
|||
|
|
|
|||
|
|
**Пример запроса:**
|
|||
|
|
```bash
|
|||
|
|
# Статистика за последние 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"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Пример ответа:**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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).
|
|||
|
|
|
|||
|
|
**Пример запроса:**
|
|||
|
|
```bash
|
|||
|
|
# Статистика за последние 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"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Пример ответа:**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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
|
|||
|
|
Статистика решения задач (пазлов):
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"total": 15, // Общее количество решенных задач
|
|||
|
|
"solved": 12, // Количество правильно решенных задач
|
|||
|
|
"unsolved": 3 // Количество нерешенных или неправильно решенных задач
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### GameModeStats
|
|||
|
|
Статистика игр для конкретного режима:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"games_played": 8, // Общее количество сыгранных игр
|
|||
|
|
"rating_change": 15, // Изменение рейтинга (может быть отрицательным)
|
|||
|
|
"final_rating": 2850, // Текущий рейтинг игрока
|
|||
|
|
"wins": 5, // Количество побед
|
|||
|
|
"losses": 2, // Количество поражений
|
|||
|
|
"draws": 1 // Количество ничьих
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### GamesStats
|
|||
|
|
Статистика игр по всем режимам:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"bullet": { /* GameModeStats */ },
|
|||
|
|
"blitz": { /* GameModeStats */ },
|
|||
|
|
"rapid": { /* GameModeStats */ }
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### UserStats
|
|||
|
|
Полная статистика пользователя:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"username": "magnus",
|
|||
|
|
"tasks": { /* TaskStats */ },
|
|||
|
|
"games": { /* GamesStats */ }
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### ActivityResponse
|
|||
|
|
Ответ API с результатами запроса:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"message": "Статистика за сегодняшний день",
|
|||
|
|
"data": { /* UserStats или null */ }
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Коды ошибок
|
|||
|
|
|
|||
|
|
- **200** - Успешный запрос
|
|||
|
|
- **404** - Пользователь не найден или неактивен
|
|||
|
|
- **500** - Внутренняя ошибка сервера
|
|||
|
|
|
|||
|
|
## Примеры ошибок
|
|||
|
|
|
|||
|
|
### Пользователь не найден
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"message": "Пользователь magnus не найден или неактивен"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Внутренняя ошибка сервера
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"detail": "Внутренняя ошибка сервера: Connection timeout"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Swagger UI
|
|||
|
|
|
|||
|
|
Интерактивная документация доступна по адресу:
|
|||
|
|
```
|
|||
|
|
http://localhost:8001/docs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## OpenAPI Schema
|
|||
|
|
|
|||
|
|
Схема OpenAPI доступна по адресу:
|
|||
|
|
```
|
|||
|
|
http://localhost:8001/openapi.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Запуск в Docker
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Сборка и запуск
|
|||
|
|
docker compose up --build -d
|
|||
|
|
|
|||
|
|
# Проверка статуса
|
|||
|
|
docker compose ps
|
|||
|
|
|
|||
|
|
# Просмотр логов
|
|||
|
|
docker compose logs
|
|||
|
|
|
|||
|
|
# Остановка
|
|||
|
|
docker compose down
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Разработка
|
|||
|
|
|
|||
|
|
### Установка зависимостей
|
|||
|
|
```bash
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Запуск в режиме разработки
|
|||
|
|
```bash
|
|||
|
|
uvicorn main:app --host 0.0.0.0 --port 8001 --reload
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Лицензия
|
|||
|
|
|
|||
|
|
MIT License
|