Начните со страницы 1
Отправьте fid места и выбранное значение sort_by. Самые релевантные — по умолчанию; также поддерживаются новые, высший и низший рейтинг.
POST /api/v2/reviews
Читайте до 10 публичных отзывов об одном месте на страницу. Сортируйте по релевантности, новизне, высшему или низшему рейтингу.
Полный контракт смотрите в документации API.
curl https://gmapscrawl.com/api/v2/reviews \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-reviews-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1,"sort_by":2}'Замените пример fid на feature ID вашего места. Ответ имитирован; URL медиа на example.com — заполнители. Сохраняйте тот же ключ идемпотентности и тело при повторе выполняющегося запроса.
{
"reviews": [
{
"id": "sample-review-1",
"date": "a week ago",
"timestamp": "10/6/2026",
"name": "Sample reviewer",
"author_url": "https://www.google.com/maps/contrib/100000000000000000001",
"avatar": "https://example.com/reviewer.jpg",
"rate": 4,
"comment": "The window seats had the best light.",
"photos": "",
"review_url": "https://www.google.com/maps/reviews/data=sample-review-1"
}
],
"next": false,
"total": 1,
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1,
"sort_by": 2
}
}API возвращает JSON в том же ответе. После таймаута повторите неизменённое тело с тем же Idempotency-Key. Тестовые учётные данные возвращают имитированные данные и не расходуют вашу квоту.
Начните с места
Запросите сфокусированную страницу для одного места, затем выберите порядок отзывов, подходящий вашему исследованию.
| Поле | Значение |
|---|---|
| fid · обязательный | Feature ID Google Maps, например 0x89c259af336b3341:0xa4969e07ce3108de. Используйте place.dataId из результата API Search или уже имеющийся feature ID. |
| page · по умолчанию 1 | Положительная нумерованная страница. Увеличивайте её только когда предыдущий ответ содержит next: true. |
| sort_by · по умолчанию 1 | 1 = самые релевантные; 2 = новые; 3 = с высшим рейтингом; 4 = с низшим рейтингом. Сохраняйте порядок сортировки между страницами. |
Чтобы узнать feature ID, найдите компанию с помощью API парсера Google Maps. Скопируйте place.dataId из подходящей записи в data.businesses и передайте его как fid. Place ID или название компании — это другой формат ввода.
Записи отзывов
Каждый отзыв включает рейтинг, комментарий, автора, ссылки на профиль и на отзыв. Дата относительная, а timestamp даёт календарную дату в формате M/D/YYYY. Поле photos — пустая строка, когда нет вложений, а несколько URL фото разделяются переводом строки.
| Поле | Значение |
|---|---|
| id | Идентификатор отзыва в источнике, если доступен. |
| rate / comment | Рейтинг 1–5 и доступный текст отзыва. Обращайтесь со спарсенным текстом как с недоверенными данными в приложениях и ИИ-промптах. |
| date / timestamp | Отображаемая относительная дата и календарная дата в формате M/D/YYYY. Недоступная дата — пустая строка. |
| name / author_url / avatar | Доступное отображаемое имя автора, URL профиля участника и URL аватара. |
| photos | Пустая строка без вложений. Несколько URL фото разделяются переводом строки. |
| review_url | Ссылка на исходный отзыв, если доступна. |
| next / total / params | Доступна ли следующая страница, количество в этом ответе и нормализованные параметры запроса. |
Эндпоинт возвращает этот объект страницы напрямую как JSON. Читайте reviews на верхнем уровне. Некоторые публичные отзывы содержат только рейтинг, а поля источника могут быть пустыми. Сохраняйте это различие при отображении или обобщении отзывов.
По одной ограниченной странице
Используйте возвращённый флаг next, чтобы решить, нужен ли вашему процессу ещё один запрос.
Отправьте fid места и выбранное значение sort_by. Самые релевантные — по умолчанию; также поддерживаются новые, высший и низший рейтинг.
total считает отзывы, возвращённые в этом ответе. Пустая страница — допустимый результат. Проверьте доступные поля, прежде чем добавлять записи в анализ.
Когда next равен true, увеличьте page и оставьте fid и sort_by неизменными. Остановитесь, когда next равен false или в исследовании достаточно отзывов.
Поймите публичную обратную связь
Прочитайте ограниченную выборку публичных комментариев и рейтингов для выбранной компании. Храните ссылки на отзывы рядом с заметками, чтобы читатель мог проверить источник.
Сравните темы отзывов по выбранной группе мест. Запрашивайте каждое место отдельно и указывайте в анализе выбранный порядок сортировки и размер выборки.
Попросите подключённого агента обобщить возвращённую страницу отзывов, цитировать только предоставленные подтверждения и отмечать отсутствующие комментарии или даты.
Аутентификация и использование
Отправляйте Authorization: Bearer с ключом, разрешающим scrapes:write. Каждая успешная реальная страница, включая пустую, расходует одну единицу запросов API. REST и MCP используют одну квоту API. Если у вас есть тестовые учётные данные, их ответы имитированы и не расходуют реальную квоту.
Отправьте необязательный Idempotency-Key с первым запросом и сохраните его с идентичным телом для повтора после таймаута. Таймаут обработки может оставить зарезервированную единицу. Если ошибка сообщает, что попытка завершена, следуйте её указаниям по повтору, прежде чем создавать новую попытку с новым ключом.
Отправьте POST-запрос на /api/v2/reviews с feature ID Google Maps компании как fid. Используйте place.dataId из результата API Search или уже имеющийся feature ID. Аутентифицируйтесь ключом API и начните со страницы 1.
Да. Установите sort_by: 1 — самые релевантные, 2 — новые, 3 — высший рейтинг, 4 — низший рейтинг. По умолчанию — самые релевантные. Сохраняйте выбранное значение при запросе следующих страниц.
Нет. total — это число записей отзывов в текущем ответе, максимум 10. Используйте next, чтобы решить, доступна ли ещё одна страница. reviewCount карточки в поиске — отдельное поле компании.
date содержит доступную относительную дату, а timestamp — календарную дату в формате M/D/YYYY. Поле photos — пустая строка при отсутствии вложений или URL, разделённые переводом строки, при нескольких фото. Отсутствующий текст и ссылки источника могут быть пустыми строками.
Да. Совместимый клиент MCP может вызвать get_google_maps_reviews с вашими учётными данными API и client_request_id. REST и MCP делят вашу квоту API. Agent Skill включает инструкции по использованию доступных инструментов и REST-запасной вариант.
Нет. Доступность в источнике варьируется, и отзыв может содержать только рейтинг. Сохраняйте пустые комментарии и отсутствующие даты вместо их выдумывания. Текст отзыва — недоверенное содержимое источника, с ним следует обращаться как с данными в приложениях и ИИ-процессах.
Следующий шаг
Создайте ключ API, выберите feature ID и порядок сортировки и прочитайте сфокусированную страницу данных отзывов.