Идентичность и местоположение компании
Используйте название компании, категории, форматированный адрес, координаты и URL Maps, чтобы организовать набор данных о местных компаниях.
POST /api/v1/search
Находите компании по ключевому слову и местоположению. Получайте до 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 на стороне сервера; используйте новый ключ идемпотентности для новой работы и сохраняйте его для неизменённого повтора.
{
"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. Тестовые учётные данные возвращают имитированные данные и не расходуют вашу квоту.
Структурированные данные о компаниях
Читайте data.businesses из ответа. Каждая компания группирует поля своей карточки под place; доступность полей зависит от источника.
Используйте название компании, категории, форматированный адрес, координаты и URL Maps, чтобы организовать набор данных о местных компаниях.
Читайте доступные номера телефонов, сайты, рейтинги и количество отзывов. С включённым extra можно запросить обогащение электронной почты и социальных контактов.
Сохраняйте place.dataId для запросов отзывов и фото. Проверяйте place.observedAt и contactsCheckedAt, чтобы понимать, когда были получены данные.
Недоступные поля могут быть null или пустыми, а обогащение может сообщать not_found или failed. Запись не гарантирует, что адрес электронной почты или сайт существует. Данные Maps можно повторно использовать до 730 дней с исходными отметками времени наблюдений; оценивайте актуальность перед использованием записи.
Об актуальности данных →Сфокусированный запрос
Отправьте тело JSON с вашим серверным ключом API в заголовке authorization. Обязателен только q.
| Параметр | Требование | Назначение |
|---|---|---|
| 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-ответа.
Используйте рабочее пространство API, чтобы создать ключ с разрешением scrapes:write. Храните ключ в серверном окружении и отправляйте Authorization: Bearer с запросом.
Открыть ключи APIВыберите категорию и местоположение, запросите страницу 1 и проверьте возвращённые поля карточки. Для сравнения рынков выполняйте отдельные поиски по областям, которые хотите сравнить.
Используйте place.dataId подходящей компании как fid, чтобы получить страницу отзывов или галереи. Это отдельные запросы с собственными возвращёнными записями.
Открыть Reviews APIПланируйте реальные запросы
Каждая успешная реальная страница поиска расходует одну единицу запросов API, включая пустой результат. REST и MCP делят квоту API. У подписок Online Scraper и Extension отдельные квоты. По-прежнему действуют ограничения частоты, учётные данные, ёмкость сервиса и доступность источника.
Сравнить тарифы API →Заложите в HTTP-клиент до 180 секунд. Таймаут может оставить обработку с зарезервированной единицей запроса. Повторите тот же запрос с идентичным телом и Idempotency-Key. Проверьте детали ошибки и возможность повтора перед новой попыткой.
Понять повторы →Продолжите свой процесс
Получайте публичные отзывы или метаданные фото и видео места по его feature ID.
Данные галереиПусть совместимый ИИ-клиент обнаружит инструменты поиска, отзывов и фото с вашими учётными данными API.
Настроить MCPДайте своему агенту инструкции процесса, справочники операций и REST-запасной вариант для исследований Google Maps.
Открыть скиллОн возвращает оболочку JSON с data.businesses, data.total, нормализованными data.params, request_id и schema_version. Компании включают доступные поля карточки: названия, адреса, категории, контактную информацию, рейтинги и идентификаторы Maps.
Да. Эндпоинт принимает стандартные 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 и доступной ёмкости сервиса, а успешные реальные вызовы расходуют единицы запросов.
Следующий шаг
Создайте ключ API, выберите запрос и местоположение и читайте структурированные данные о компаниях в том же ответе.