POST /api/v2/photos

API парсера фото Google Maps

Читайте до 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 — заполнители. Сохраняйте тот же ключ идемпотентности и тело при повторе выполняющегося запроса.

Ответ

Пример JSON
{
  "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.

Параметры запроса API парсера фото Google Maps
ПолеЗначение
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 верхнего уровня ведёт на галерею места.

Поля ответа API парсера фото Google Maps
ПолеЗначение
photoUrlДоступный URL фото или превью-изображение для видеоэлемента.
videoUrlНеобязательный URL видео. Присутствует у записей видео, содержащих источник видео.
urlURL галереи Google Maps для запрошенного места.
nextДоступна ли ещё одна нумерованная страница галереи.
totalКоличество в этом ответе, от нуля до 20. Это не общий размер галереи места.
paramsНормализованные fid и page, использованные для этого ответа.

Эндпоинт возвращает этот объект страницы напрямую как JSON. Читайте photos на верхнем уровне. API возвращает метаданные и ссылки на медиа. Доступность изображения или видео зависит от источника; элемент галереи не гарантирует скачиваемое видео.

По одной ограниченной странице

Читайте до 20 элементов галереи в каждом ответе.

Используйте возвращённый флаг next, чтобы решить, нужен ли вашему процессу ещё один запрос.

01

Начните со страницы 1

Отправьте fid места и страницу 1. Записи идут в порядке, заданном галереей места.

02

Проверьте текущую страницу

total считает элементы галереи, возвращённые в этом ответе. Пустая страница — допустимый результат. Проверьте доступные поля, прежде чем добавлять записи в анализ.

03

Продолжайте осознанно

Когда next равен true, увеличьте page и сохраните тот же fid. Остановитесь, когда next равен false или в процессе достаточно медиазаписей.

Изучите место визуально

Внесите метаданные галереи в свой исследовательский процесс.

01

Исследование карточек компаний

Изучите галерею, связанную с выбранной компанией, и сохраните ссылку на исходную галерею рядом с возвращёнными записями.

02

Организация фото и видео

Отделяйте записи фото от записей видео по необязательному полю videoUrl и показывайте доступные превью в собственном интерфейсе исследования.

03

Обзор галереи с помощью агента

Пусть подключённый агент получит одну страницу метаданных галереи и перечислит доступные ссылки на медиа для дальнейшей проверки.

Аутентификация и использование

Используйте ключ API для каждой страницы.

Общая квота API

Отправляйте Authorization: Bearer с ключом, разрешающим scrapes:write. Каждая успешная реальная страница, включая пустую, расходует одну единицу запросов API. REST и MCP используют одну квоту API. Если у вас есть тестовые учётные данные, их ответы имитированы и не расходуют реальную квоту.

Тарифы и лимиты API →

Привязывайте повторы к запросу

Отправьте необязательный Idempotency-Key с первым запросом и сохраните его с идентичным телом для повтора после таймаута. Таймаут обработки может оставить зарезервированную единицу. Если ошибка сообщает, что попытка завершена, следуйте её указаниям по повтору, прежде чем создавать новую попытку с новым ключом.

Читать об ошибках и повторах →

Часто задаваемые вопросы

Что возвращает API парсера фото Google Maps?

Он возвращает до 20 записей метаданных фото и видео для места в каждом ответе JSON. У каждой записи есть photoUrl, а у записей видео может быть и videoUrl. url верхнего уровня ведёт на галерею места.

Как получить feature ID галереи места?

Используйте place.dataId из подходящей компании в ответе API Search и отправьте его как fid. Можно также указать имеющийся feature ID Maps. Отправляйте тот же fid при запросе следующих страниц галереи.

Скачивает ли Photos API файлы изображений или видео?

Эндпоинт возвращает метаданные и URL медиа в JSON. Ваше приложение может проверять доступные ссылки и источник галереи. Доступность источника определяет, какие записи и URL возвращаются; photoUrl может быть превью-изображением видео.

Как пагинировать галерею Google Maps?

Начните со страницы 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 места и получите структурированные метаданные фото и видео.