Основные понятия

Группа, ссылка, отзыв; нормализация оценок, дедупликация, площадки.

Группа → Ссылка → Отзыв

Три сущности связаны иерархией:

Группа (group) — ваш объект учёта: один отель, одна клиника, один ресторан. У группы есть человекочитаемое имя — поле name.
Ссылка (link) — страница этого объекта на конкретной площадке. В группе обычно несколько ссылок: Яндекс.Карты, 2ГИС, Otzovik и т. д. — по одной на площадку. У ссылки есть source_id (какая площадка) и scrape_status (как идёт сбор).
Отзыв (review) — единица отзыва, привязанная к ссылке (link_id) и площадке (source_id), лежащая внутри группы.

Rewio периодически обходит все активные ссылки и складывает найденные отзывы в соответствующую группу. Читаете вы их на уровне группы: GET /v2/reviews?group_id=....

Нормализация оценок (1–5)

Площадки используют разные шкалы (5, 10, 100 баллов, «палец вверх»). Rewio приводит всё к единой шкале 1–5:

rating — нормализованная оценка 1–5, может быть дробной (например 4.5).
rating_original — исходная оценка площадки, как она была (для прозрачности).
Часть площадок вообще без числовой оценки (только текст) — у таких отзывов rating может быть null.

Один и тот же отзыв с одной площадки не задваивается, даже если встретился при нескольких обходах. Ключ уникальности — пара «ссылка + идентификатор отзыва на площадке». Практический вывод: при повторном обходе вы получаете обновления существующих отзывов (например, появившийся ответ отеля), а не дубликаты.

Анатомия отзыва

Основные поля review (полный список — в справочнике GET /v2/reviews):

Поле	Тип	Смысл
`id`	int	Идентификатор отзыва в Rewio.
`source_id` / `link_id`	int	Площадка и ссылка, откуда отзыв.
`author`	string	Имя автора, как на площадке.
`text`	string \| null	Текст отзыва (может быть пустым у оценок-без-текста).
`rating`	number \| null	Нормализованная оценка 1–5 (см. выше).
`rating_original`	string \| null	Исходная оценка площадки.
`review_date`	datetime	Дата публикации — местное время площадки, не UTC.
`review_url`	string \| null	Прямая ссылка на сам отзыв на площадке.
`reply_text` / `reply_date`	string \| null	Ответ объекта на отзыв, если есть.
`has_images` / `images`	bool / list	Прикреплённые фото.
`has_videos` / `videos`	bool / list	Прикреплённые видео.
`updated_at`	datetime (UTC)	Когда запись отзыва последний раз менялась у нас — ось для инкрементальной синхронизации.
`is_hidden` / `is_pinned`	bool	Пометки показа: скрытие ненужных и закрепление нужных отзывов в выдаче.

Три оси времени

Не путайте три разных времени — у них разные имена и назначения:

review_date — когда отзыв опубликован на площадке (местное время площадки).
created_at — когда мы его впервые захватили.
updated_at — когда запись у нас последний раз изменилась (UTC).

Фильтр по диапазону публикации — published_from / published_to (включительно). Курсор «что изменилось после» — updated_after. Подробнее в гайде по отзывам.

Площадки

Список поддерживаемых площадок и их идентификаторов отдаёт GET /v2/sources. Значение source в каждом отзыве совпадает с именем площадки из этого списка — по нему удобно фильтровать (source_ids) и группировать.