POST /api/v1/search

API парсера Google Maps

Находите компании по ключевому слову и местоположению. Получайте до 20 структурированных записей о компаниях в том же ответе JSON — готовых для вашего приложения или исследовательского процесса.

Примеры запросов

Полный контракт смотрите в документации API.

curl https://gmapscrawl.com/api/v1/search \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seattle-coffee-search-001" \
  -d '{"q":"coffee shops in Seattle","page":1,"extra":false}'

Пример пустого ответа. Реальный поиск возвращает доступные компании. Держите ключ API на стороне сервера; используйте новый ключ идемпотентности для новой работы и сохраняйте его для неизменённого повтора.

Ответ

Пример JSON
{
  "data": {
    "total": 0,
    "params": {
      "q": "coffee shops in Seattle",
      "page": 1,
      "hl": "en",
      "extra": false
    },
    "businesses": []
  },
  "request_id": "req_example",
  "schema_version": "2026-09-22"
}

API возвращает JSON в том же ответе. После таймаута повторите неизменённое тело с тем же Idempotency-Key. Тестовые учётные данные возвращают имитированные данные и не расходуют вашу квоту.

Структурированные данные о компаниях

От поиска в Maps к записям, которыми можно пользоваться.

Читайте data.businesses из ответа. Каждая компания группирует поля своей карточки под place; доступность полей зависит от источника.

01

Идентичность и местоположение компании

Используйте название компании, категории, форматированный адрес, координаты и URL Maps, чтобы организовать набор данных о местных компаниях.

02

Контакты и репутация

Читайте доступные номера телефонов, сайты, рейтинги и количество отзывов. С включённым extra можно запросить обогащение электронной почты и социальных контактов.

03

Идентификаторы и даты наблюдений

Сохраняйте place.dataId для запросов отзывов и фото. Проверяйте place.observedAt и contactsCheckedAt, чтобы понимать, когда были получены данные.

Отсутствующие и устаревшие данные остаются видимыми

Недоступные поля могут быть null или пустыми, а обогащение может сообщать not_found или failed. Запись не гарантирует, что адрес электронной почты или сайт существует. Данные Maps можно повторно использовать до 730 дней с исходными отметками времени наблюдений; оценивайте актуальность перед использованием записи.

Об актуальности данных →

Сфокусированный запрос

Выберите запрос, страницу и обогащение.

Отправьте тело JSON с вашим серверным ключом API в заголовке authorization. Обязателен только q.

Параметры API Google Maps Search
ПараметрТребованиеНазначение
qОбязательныйКлючевое слово компании и местоположение, например кофейни в Сиэтле. Используйте 2–200 символов.
pageПо умолчанию: 1Нумерованная страница поиска от 1 до 10. Каждый запрос возвращает не более 20 компаний.
llНеобязательныйВьюпорт Maps вида @47.6062,-122.3321,12z для уточнения местоположения поиска.
hlПо умолчанию: enКод языка, используемый для поиска.
glНеобязательныйДвухбуквенный код страны, уточняющий запрос. Это не строгий географический фильтр.
extraПо умолчанию: falseУстановите true, чтобы запросить доступное обогащение электронной почты и социальных контактов. Это может занять больше времени.

Ответ отражает нормализованные параметры в data.params. Значение data.total считает компании в этом ответе, а не общее число компаний на Google Maps. Явно выбирайте другую страницу, когда вашему процессу нужно больше результатов.

Создайте первую интеграцию

Один запрос. Полезный следующий шаг.

API Search синхронный: читайте результат прямо из HTTP-ответа.

01

Создайте свой ключ API

Используйте рабочее пространство API, чтобы создать ключ с разрешением scrapes:write. Храните ключ в серверном окружении и отправляйте Authorization: Bearer с запросом.

Открыть ключи API
02

Поиск по ограниченной области

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

03

Следуйте идентификатору места

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

Открыть Reviews API

Планируйте реальные запросы

Предсказуемые страницы, явные лимиты.

Использование и доступность

Каждая успешная реальная страница поиска расходует одну единицу запросов API, включая пустой результат. REST и MCP делят квоту API. У подписок Online Scraper и Extension отдельные квоты. По-прежнему действуют ограничения частоты, учётные данные, ёмкость сервиса и доступность источника.

Сравнить тарифы API →

Таймауты и повторы

Заложите в HTTP-клиент до 180 секунд. Таймаут может оставить обработку с зарезервированной единицей запроса. Повторите тот же запрос с идентичным телом и Idempotency-Key. Проверьте детали ошибки и возможность повтора перед новой попыткой.

Понять повторы →

Продолжите свой процесс

Больше способов использовать те же данные о компаниях.

01

Данные отзывов и галереи

Получайте публичные отзывы или метаданные фото и видео места по его feature ID.

Данные галереи
02

Подключите клиент MCP

Пусть совместимый ИИ-клиент обнаружит инструменты поиска, отзывов и фото с вашими учётными данными API.

Настроить MCP
03

Установите Agent Skill

Дайте своему агенту инструкции процесса, справочники операций и REST-запасной вариант для исследований Google Maps.

Открыть скилл

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

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

Он возвращает оболочку JSON с data.businesses, data.total, нормализованными data.params, request_id и schema_version. Компании включают доступные поля карточки: названия, адреса, категории, контактную информацию, рейтинги и идентификаторы Maps.

Можно ли использовать API из Python или JavaScript?

Да. Эндпоинт принимает стандартные HTTP POST-запросы с JSON и Bearer-аутентификацией. Примеры выше используют стандартную библиотеку Python и серверный fetch на JavaScript. Подойдёт любой HTTP-клиент, способный отправить эти заголовки и тело.

Сколько компаний может вернуть один запрос?

Страница поиска возвращает от нуля до 20 компаний. Параметр page принимает значения от 1 до 10. Каждая успешная реальная страница, включая пустую, расходует одну единицу запросов API; поиск не гарантирует, что каждая страница содержит 20 компаний.

Можно ли получить отдельные отзывы и фото?

Да. Скопируйте place.dataId из компании и передайте его как fid в отдельный API Reviews или Photos. Эти эндпоинты возвращают одну ограниченную страницу на запрос. Обзор API ссылается на поля, примеры и правила пагинации каждого эндпоинта.

Есть ли адреса электронной почты у каждой компании?

Нет. Установите extra в true, чтобы запросить доступное обогащение контактов. Сайты, адреса и профили в соцсетях могут отсутствовать. Проверяйте enrichmentState и fieldStates и явно отражайте недоступные данные в своём приложении.

Как тестировать интеграцию?

Если у вас есть тестовые учётные данные, их ответы имитированы и не расходуют реальную квоту API. Помечайте такие результаты как имитированные. Реальные ключи требуют активного права API и доступной ёмкости сервиса, а успешные реальные вызовы расходуют единицы запросов.

Следующий шаг

Создайте свой первый поиск в Google Maps.

Создайте ключ API, выберите запрос и местоположение и читайте структурированные данные о компаниях в том же ответе.