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
Отправьте запрос и локацию, отслеживайте асинхронную задачу, затем читайте нормализованные записи мест с курсорной пагинацией.
- Подготовьте непустые query и location; при необходимости добавьте country, координаты, zoom_level и results_limit от 1 до 2 000.
- Отправьте запрос методом POST на /v1/google-maps/search и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или не сообщит об ошибке.
- Читайте 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 для сравнения состояния на определенный момент.
Связанные API
Помимо Google Maps Search API, используйте эти API, когда нужен другой тип публичных данных Google Maps.