Начните со страницы 1
Отправьте fid места и страницу 1. Записи идут в порядке, заданном галереей места.
POST /api/v2/photos
Читайте до 20 элементов галереи одного места на страницу. Получайте URL фото и видео в том порядке, в котором они идут в галерее.
Полный контракт смотрите в документации API.
curl https://gmapscrawl.com/api/v2/photos \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-photos-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1}'Замените пример fid на feature ID вашего места. Ответ имитирован; URL медиа на example.com — заполнители. Сохраняйте тот же ключ идемпотентности и тело при повторе выполняющегося запроса.
{
"photos": [
{
"photoUrl": "https://example.com/gallery-image.jpg"
},
{
"photoUrl": "https://example.com/gallery-preview.jpg",
"videoUrl": "https://example.com/gallery-video.mp4"
}
],
"next": false,
"total": 2,
"url": "https://www.google.com/maps/uv?pb=!1s0x89c259af336b3341:0xa4969e07ce3108de!15sCgIgAQ",
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1
}
}API возвращает JSON в том же ответе. После таймаута повторите неизменённое тело с тем же Idempotency-Key. Тестовые учётные данные возвращают имитированные данные и не расходуют вашу квоту.
Начните с места
Запросите метаданные изображений и видео одного места по его feature ID.
| Поле | Значение |
|---|---|
| fid · обязательный | Feature ID Google Maps, например 0x89c259af336b3341:0xa4969e07ce3108de. Используйте place.dataId из результата API Search или уже имеющийся feature ID. |
| page · по умолчанию 1 | Положительная нумерованная страница. Увеличивайте её только когда предыдущий ответ содержит next: true. |
Чтобы узнать feature ID, найдите компанию с помощью API парсера Google Maps. Скопируйте place.dataId из подходящей записи в data.businesses и передайте его как fid. Place ID или название компании — это другой формат ввода.
Записи галереи
У каждого элемента есть photoUrl для изображения или превью видео. У видеоэлементов также есть videoUrl. url верхнего уровня ведёт на галерею места.
| Поле | Значение |
|---|---|
| photoUrl | Доступный URL фото или превью-изображение для видеоэлемента. |
| videoUrl | Необязательный URL видео. Присутствует у записей видео, содержащих источник видео. |
| url | URL галереи Google Maps для запрошенного места. |
| next | Доступна ли ещё одна нумерованная страница галереи. |
| total | Количество в этом ответе, от нуля до 20. Это не общий размер галереи места. |
| params | Нормализованные fid и page, использованные для этого ответа. |
Эндпоинт возвращает этот объект страницы напрямую как JSON. Читайте photos на верхнем уровне. API возвращает метаданные и ссылки на медиа. Доступность изображения или видео зависит от источника; элемент галереи не гарантирует скачиваемое видео.
По одной ограниченной странице
Используйте возвращённый флаг next, чтобы решить, нужен ли вашему процессу ещё один запрос.
Отправьте fid места и страницу 1. Записи идут в порядке, заданном галереей места.
total считает элементы галереи, возвращённые в этом ответе. Пустая страница — допустимый результат. Проверьте доступные поля, прежде чем добавлять записи в анализ.
Когда next равен true, увеличьте page и сохраните тот же fid. Остановитесь, когда next равен false или в процессе достаточно медиазаписей.
Изучите место визуально
Изучите галерею, связанную с выбранной компанией, и сохраните ссылку на исходную галерею рядом с возвращёнными записями.
Отделяйте записи фото от записей видео по необязательному полю videoUrl и показывайте доступные превью в собственном интерфейсе исследования.
Пусть подключённый агент получит одну страницу метаданных галереи и перечислит доступные ссылки на медиа для дальнейшей проверки.
Аутентификация и использование
Отправляйте Authorization: Bearer с ключом, разрешающим scrapes:write. Каждая успешная реальная страница, включая пустую, расходует одну единицу запросов API. REST и MCP используют одну квоту API. Если у вас есть тестовые учётные данные, их ответы имитированы и не расходуют реальную квоту.
Отправьте необязательный Idempotency-Key с первым запросом и сохраните его с идентичным телом для повтора после таймаута. Таймаут обработки может оставить зарезервированную единицу. Если ошибка сообщает, что попытка завершена, следуйте её указаниям по повтору, прежде чем создавать новую попытку с новым ключом.
Он возвращает до 20 записей метаданных фото и видео для места в каждом ответе JSON. У каждой записи есть photoUrl, а у записей видео может быть и videoUrl. url верхнего уровня ведёт на галерею места.
Используйте place.dataId из подходящей компании в ответе API Search и отправьте его как fid. Можно также указать имеющийся feature ID Maps. Отправляйте тот же fid при запросе следующих страниц галереи.
Эндпоинт возвращает метаданные и URL медиа в JSON. Ваше приложение может проверять доступные ссылки и источник галереи. Доступность источника определяет, какие записи и URL возвращаются; photoUrl может быть превью-изображением видео.
Начните со страницы 1. total считает записи в этом ответе. Если next равен true, запросите следующую страницу с тем же fid и новым ключом идемпотентности для нового запроса. Остановитесь, когда next равен false или в процессе достаточно записей.
Photos API принимает fid и page. Он возвращает элементы в порядке галереи, заданном источником; параметра sort_by, как у отзывов, нет.
Да. Подключите совместимый клиент MCP, чтобы использовать get_google_maps_photos с вашими учётными данными API. Agent Skill добавляет инструкции процесса и REST-запасной вариант. Каждая успешная реальная страница галереи расходует общую квоту API.
Следующий шаг
Создайте ключ API, укажите feature ID места и получите структурированные метаданные фото и видео.