google-maps/
search

Ищите публичные места в Google Maps по запросу и локации: нормализованные названия, категории, адреса, контакты, рейтинги, число отзывов, URL и координаты.

Google Maps Search API

Запрос и локация
Географический контекст по желанию
1–2 000 результатов в запросе
Нормализованные записи мест
0,15 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

Google Maps Search

Google Maps Search превращает запрос по компании, категории или месту вместе с обязательной локацией в структурированные публичные записи мест. Каждый сохраненный результат следует схеме PlaceItem, не зависящей от провайдера, поэтому доступные поля идентичности, адреса, контактов, рейтинга, числа отзывов и координат можно передавать в исследовательские системы и системы обогащения, не привязывая клиентов к ключам ответа конкретного источника.

Возможности Google Maps Search API

  • Поиск по запросу и локацииСочетайте обязательный непустой запрос, например coffee, с обязательной локацией, например New York, NY, чтобы находить подходящие публичные места.
  • Дополнительные географические настройкиДобавляйте country, пару широта–долгота и zoom_level, когда поиску нужен более явный географический контекст; неуказанные необязательные поля не подставляются.
  • Нормализованные данные о месте и контактыПолучайте стабильные поля PlaceItem: ID, исходные URL, названия, категории, адреса, публичные номера телефонов, сайты и время сбора, если они доступны.
  • Рейтинги и географические координатыСохраняйте доступные рейтинги, число отзывов, город, регион, страну, широту и долготу для каждого места и корректно обрабатывайте отсутствующие поля источника.

Параметры Google Maps Search API

ПараметрыОбязательныйОписание
queryОбязательныйОбязательный непустой поисковый запрос: место, компания или категория.
locationОбязательныйОбязательная непустая область поиска в понятном человеку виде: город, регион или адрес. Если обе координаты не указаны, она объединяется с запросом для поиска.
countryНеобязательныйНеобязательное непустое название или код страны, передаваемые как географический контекст.
latitudeНеобязательныйНеобязательная широта от -90 до 90. Указывается только вместе с долготой.
longitudeНеобязательныйНеобязательная долгота от -180 до 180. Указывается только вместе с широтой.
zoom_levelНеобязательныйНеобязательный целочисленный масштаб карты от 0 до 21.
results_limitНеобязательныйМаксимальное число сохраняемых записей мест; по умолчанию 100, принимаются целые числа от 1 до 2 000.

Как использовать Google Maps Search API

Отправьте запрос и локацию, отслеживайте асинхронную задачу, затем читайте нормализованные записи мест с курсорной пагинацией.

  1. Подготовьте непустые query и location; при необходимости добавьте country, координаты, zoom_level и results_limit от 1 до 2 000.
  2. Отправьте запрос методом POST на /v1/google-maps/search и сохраните возвращенный task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или не сообщит об ошибке.
  4. Читайте data.results.items и передавайте next_cursor эндпоинту задачи, пока has_more остается true.
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Сценарии использования Google Maps Search API

  • Поиск локального бизнеса: Составляйте ограниченный список публичных компаний, соответствующих категории или услуге в заданном городе, районе или по адресу.
  • Обогащение данных о локациях: Добавляйте доступные названия, категории, адреса, телефоны, сайты и координаты к кандидатам-местам, которые уже есть в CRM или в очереди исследования.
  • Исследование рынка и покрытия: Сравнивайте число собранных мест, категории, рейтинги и объем отзывов в независимо отправленных географических поисках.
  • Подготовка шорт-листа мест: Используйте публичные URL, контактные поля, контекст рейтинга и координаты, чтобы отбирать места для отдельной проверки или сбора подробных сведений.

Практические советы по Google Maps Search API

  • Указывайте конкретную категорию или название бизнеса и понятный город, район или адрес в location; размытые сочетания дают широкие или неоднозначные совпадения.
  • Передавайте country, координаты или zoom_level, только если они дают проверенный географический контекст. Указывайте latitude и longitude вместе и держите оба значения в задокументированных диапазонах.
  • Держите results_limit близко к нужному числу записей. Он задает потолок сбора, а limit в GET-запросе задачи определяет, сколько сохраненных записей возвращается на одной странице ответа.
  • Продолжайте с next_cursor, пока has_more не станет false, если сохраненных результатов больше, чем помещается на первой странице ответа задачи.
  • Считайте описания, контактные поля, рейтинги, число отзывов и координаты необязательными публичными данными и сохраняйте collected_at для сравнения состояния на определенный момент.

Помимо Google Maps Search API, используйте эти API, когда нужен другой тип публичных данных Google Maps.

Другие платформы

Объединяйте данные Google Maps с публичными данными других поддерживаемых соцсетей.

Google Maps Search API — FAQ

Google Maps Search API — это асинхронный интерфейс для поиска публичных мест по обязательным запросу и локации. Он возвращает не зависящие от провайдера записи PlaceItem с доступными полями идентичности, категории, адреса, контактов, рейтинга, числа отзывов, URL и географии.

query и location — обязательные непустые строки. country, latitude, longitude, zoom_level и results_limit необязательны.

Да. Текущая спецификация запроса принимает координаты только парой. Не указывайте ни одну из них, чтобы объединить location с query, или передайте latitude от -90 до 90 вместе с longitude от -180 до 180.

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

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

Каждая сохраненная запись места стоит 0,15 кредита SocQ. Предоплата рассчитывается по results_limit (или по 100, если он не указан); после успешного завершения итог считается по фактическому числу сохраненных результатов, а за пустой набор результатов плата не взимается.