Нужно найти кофейни в районе, получить адреса и вывести их в приложении. Вы открываете руководство, копируете пример Google Places, создаёте проект в Google Cloud и доходите до подключения API. В примере всё выглядит просто, но в консоли нужный вариант сервиса уже недоступен.
В актуальной справке Google указано, что с октября 2026 года Places API Legacy нельзя включить в новых Google Cloud-проектах. Для существующих проектов поддержка сохраняется. Если начинаете интеграцию сейчас, проверьте, какую версию API использует найденный пример. Документация Google Places Legacy.
Для карты с карточками заведений пригодится официальный Places API New. Для работы с результатами поиска по картам можно рассмотреть Xylop. Возьмём одну задачу — найти кофейни — и посмотрим, как устроены запросы и какие сведения нужны приложению.
Сначала посмотрите на адрес запроса
Один из признаков старого руководства — адрес вида maps.googleapis.com/maps/api/place/textsearch/json. В Text Search New запрос отправляют на places.googleapis.com/v1/places:searchText методом POST. Параметры передают в JSON, а список полей ответа указывают отдельно. При переходе понадобится обновить и разбор результата. Text Search New.
Откройте проект Google Cloud, проверьте платёжный аккаунт, включите Places API New и разрешите эту версию API в ограничениях ключа. После этого имеет смысл разбираться с кодом. Иначе ошибка настройки будет мешать проверять даже правильно собранный запрос. Подготовка к миграции, подключение биллинга.
Какие поля нужны вашему приложению
Для первого экрана со списком кофеен хватит названия, адреса и координат. Добавьте идентификатор места, чтобы связать выбранную строку с дальнейшими действиями пользователя. Набор полей стоит определить до первого запроса. Тогда будет понятно, что проверять в ответе и за что вы платите.
В Place Details New, Text Search New и Nearby Search New список возвращаемых полей обязателен. Его передают, например, в заголовке X-Goog-FieldMask. Для методов поиска пути начинаются с places., потому что в ответе приходит массив мест. Выбор полей в Places API New.
Для списка кофеен запрос может выглядеть так. В переменной окружения GOOGLE_MAPS_API_KEY должен быть ваш ключ Google Maps Platform. Пример для Bash составлен по документации Google. В рамках этой статьи запрос к Google не выполнялся.
curl --request POST \
'https://places.googleapis.com/v1/places:searchText' \
--header 'Content-Type: application/json' \
--header "X-Goog-Api-Key: ${GOOGLE_MAPS_API_KEY}" \
--header 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location' \
--data '{
"textQuery": "coffee near Lower East Side, New York",
"languageCode": "en"
}'Ключ и выбранные поля в этом примере относятся к официальному API Google. Ответ придёт в массиве places. Сам набор найденных заведений проверяйте на своём запросе. Google предупреждает, что одинаковые запросы могут возвращать различающиеся списки. Формат запроса и ответа Text Search New.
Неожиданный момент при миграции скрывается в поле name. Раньше в нём было название заведения. В новой версии это имя ресурса вида places/PLACE_ID, а читаемое название находится в displayName.text. Если оставить старый код, вместо названия кофейни можно получить служебную строку. Изменения формата ответа.
| Что получаем | Legacy | Places API New |
|---|---|---|
| Название заведения | name | displayName.text |
| Идентификатор места | place_id | id |
| Адрес | formatted_address | formattedAddress |
| Координаты | geometry.location | location |
Набор полей в примере относится к Text Search Pro: в нём запрошены название, адрес и координаты. По правилам Google запрос оплачивается по самому высокому SKU из запрошенных. Перед добавлением рейтингов, телефонов и других сведений проверьте их категории. Конкретную стоимость считайте по действующим ценам для своего объёма. Поля и SKU Text Search, правила тарификации.
Если задача начинается с поисковой выдачи
Теперь немного изменим задачу. Допустим, вы делаете внутренний инструмент, которому нужен список результатов по запросу «coffee» с заданной областью карты. Из ответа нужно взять названия и адреса, посмотреть координаты, а затем решить, какие места изучать дальше.
В Xylop для такого поиска есть engine google_maps. Режим type=search принимает поисковую фразу q, область карты ll, язык hl и страну gl. Описание параметров и примеры SDK собраны на странице Google Maps. Документация Xylop.
Вот запрос к Xylop с географией около Манхэттена. В переменной XYLOP_API_KEY должен быть ключ из вашего кабинета Xylop.
curl --get 'https://api.xylop.ru/search.json' \
--data-urlencode 'engine=google_maps' \
--data-urlencode 'type=search' \
--data-urlencode 'q=coffee' \
--data-urlencode 'll=@40.7223,-73.9874,14z' \
--data-urlencode 'hl=en' \
--data-urlencode 'gl=us' \
--data-urlencode "api_key=${XYLOP_API_KEY}"В проверке от 5 ноября 2026 года такой поиск через C# SDK Xylop вернул HTTP 200 и 20 элементов в local_results. Ниже сокращённый фрагмент первого результата из сохранённого ответа. Он показывает структуру данных на момент проверки.
{
"local_results": [
{
"title": "BUDDIES COFFEE",
"place_id": "ChIJo20fEQpZwokRW7sSJjFierw",
"address": "226 E 3rd St, New York, NY 10009",
"gps_coordinates": {
"latitude": 40.722209,
"longitude": -73.98217249999999
}
}
]
}Число 20 относится к этому ответу. Если повторите запрос в другое время или измените область карты, сохраните собственный результат для сравнения. В той же проверке запросы отдельных карточек через type=place завершались HTTP 502. Поэтому поиск списка и получение подробностей выбранного места стоит проверять по отдельности.
Тот же поисковый запрос можно собрать через Python SDK Xylop. Пример ниже соответствует интерфейсу SDK из репозитория проекта. Ключ клиент добавляет сам.
import os
from xylop_api_client import XylopSearchClient, XylopSearchEngines
client = XylopSearchClient(os.environ["XYLOP_API_KEY"])
response = client.search(
XylopSearchEngines.GOOGLE_MAPS,
{
"type": "search",
"q": "coffee",
"ll": "@40.7223,-73.9874,14z",
"hl": "en",
"gl": "us",
},
)
if not isinstance(response, dict):
raise RuntimeError("Unexpected response format")
if response.get("error"):
raise RuntimeError(response["error"])
for place in response.get("local_results") or []:
print(place.get("title"), place.get("address"))Python-клиент возвращает JSON как словари и списки. Пример выше проверен локально на сохранённом ответе: он вывел все 20 строк. В C# можно работать с JSON напрямую или разобрать его в типизированную модель. Для своей интеграции сравните оба представления ответа, особенно если вам нужны дополнительные поля. SDK и контракт Google Maps в Xylop.
Как выбрать способ получения данных
Для официальной интеграции Google Maps Platform начните с Places API New и нужного метода поиска или получения карточки. Если приложение обрабатывает локальную поисковую выдачу, попробуйте Google Maps engine Xylop на своём наборе запросов. Сравните результаты с тем, что должен делать продукт.
| Задача | С чего начать | Что проверить |
|---|---|---|
| Показать место в приложении на Google Maps Platform | Place Details New и нужные поля карточки | Идентификатор, состав полей, атрибуцию и стоимость |
| Найти места по фразе через официальный API | Text Search New с FieldMask | Географические параметры, язык и соответствие результатов запросу |
| Разобрать результаты локального поиска через Xylop | google_maps с type=search | Область карты, local_results и нужные поля каждого результата |
| Получить подробности места через Xylop | Отдельная проверка type=place | Успешный ответ и наличие полей для вашего места. Проверка 5 ноября дала HTTP 502 |
Удобно выписать несколько обязательных условий. Например, нужны название и координаты каждого результата, поиск должен работать в выбранном городе, а пустой адрес должен обрабатываться без ошибки. Если нужен телефон, сайт или информация о посещениях, включите каждое поле в отдельную проверку. Название метода в документации само по себе ещё не показывает, какие сведения придут для конкретного места.
Идентификаторы тоже храните вместе с указанием источника и назначения. В ответе Xylop могут встречаться place_id и data_id, а в Places API New — id и имя ресурса name. Перед передачей значения в следующий метод проверьте, какой именно идентификатор он принимает.
Заранее определите, будете ли вы показывать данные пользователю, сохранять их или регулярно обновлять. У Google Places есть требования к атрибуции и ограничения на хранение контента с отдельными исключениями для идентификаторов мест. Эти правила нужно учесть в архитектуре приложения. Для данных другого провайдера проверьте условия, применимые к выбранному сервису и источнику. Политики Places API.
Начните с одного района
Для первого теста возьмите район, в котором знаете несколько заведений. Сохраните параметры запроса и время проверки. Посмотрите, нашлись ли знакомые места, совпадают ли адреса и координаты, какие значения отсутствуют. Для сравнения провайдеров зафиксируйте одинаковые географию и язык.
Затем повторите поиск с другим масштабом карты. Проверьте дубли, порядок результатов и переход к следующей странице, если он предусмотрен выбранным методом. До массового запуска сверяйте квоты и ограничения с документацией сервиса. Число строк одного удачного ответа ещё не показывает полноту покрытия района.
Поисковый ответ удобно сохранить как тестовый пример для своего обработчика. Пустые поля, отсутствие результатов и ошибки API должны приводить к понятному состоянию приложения. Преобразовывать неудачный запрос в пустой список опасно для аналитики — такой список легко принять за отсутствие заведений в районе.
Если вам подходит работа с локальной выдачей, откройте Google Maps в документации Xylop, подставьте свой район и выполните первый запрос. Начните с названия, адреса и координат. Следующее поле добавляйте, когда будет понятно, для чего оно нужно вашему приложению. Начать с Google Maps engine.