🍽️ Restaurant Data Analysis API

Аналитический инструмент для ресторанной индустрии
Реализация API для оценки популярности, локационной статистики и тональности отзывов — без ML, с фокусом на точность и интерпретируемость.

🧑‍💻 Другие участники проекта

• pul-stack
• nanashi

Роль Student 2 выполнял у pul-stack

📝 О проекте

Данный проект реализует систему анализа данных ресторанов в соответствии со спецификацией Restaurant Data Analysis System Specification v1.0.
Цель — предоставить интерпретируемые метрики для маркетологов, аналитиков и владельцев ресторанов:

• 📊 Топ ресторанов по рейтингу и активности
• 🌍 Сравнение кухонь по городам и штатам
• 😊 Анализ тональности отзывов без сторонних NLP-библиотек — только прозрачное правило на ключевых словах

⚠️ Примечание по датасету:
Оригинальный датасет Yelp Dataset на Kaggle временно недоступен из-за ошибки загрузки ресурсов (см. ошибка CSS).
Поэтому в проекте используется генератор синтетических данных, который имитирует реальные характеристики Yelp:

• Распределение рейтингов (смещение к 4.0±0.6)
• Неравномерное число отзывов (от 10 до 500+)
• Реалистичные имена, кухни, локации и обзоры
• Поддержка неоднородного регистра и пустых полей

Генератор настраиваем и легко заменяется на загрузку из CSV при наличии реального датасета.

🛠️ Технологии и подходы

📂 Структура репозитория

restaurant-analysis-api/
├── README.md                     # Этот файл
├── dev/
│   ├── solution.py               # Готовый код - решение
├── spec/
│   ├── codex.md                  # Составленные мной требования для проекта
├── demo/
│   ├── top_10_all.json           # Топ-10 ресторанов (≥20 отзывов)
│   ├── top_10_all.json           # Топ-10 ресторанов (≥20 отзывов)
│   ├── top_italian_ca.json       # Лучшие итальянские в Калифорнии
│   ├── cuisine_stats_ny.json     # Статистика кухонь в Нью-Йорке
│   ├── cuisine_stats_tx.json     # Статистика кухонь в Техасе
│   ├── sentiment_samples.json    # Тональность для "Pizza", "Sushi", "Taco"
├── tasks/
│   ├── task_variants.md          # Варианты заданий (включены изначально)
└── CONTRIBUTING.md               # Подроное описание задания для студентов

🚀 Как запустить

В Google Colab (рекомендуется для быстрого старта)

1. Создайте новый ноутбук
2. Вставьте готовую ячейку из документации (или запросите у автора)
3. Запустите — через 8–12 секунд появится папка
   demo/
   с 5 JSON-файлами

Локально

✅ После запуска результаты сохраняются в

demo/

— никаких интерактивных вводов не требуется.

📤 Примеры выходных данных

demo/top_10_all.json

demo/sentiment_samples.json

✅ Критерии приёмки — статус

🎯 Заключение

Проект полностью завершён, соответствует техническому заданию и готов к:

• Ревью кода
• Интеграции в отчётные системы
• Расширению (например, добавлению FastAPI или поддержки реального CSV из Kaggle при восстановлении доступа)