Places Library подключение

Архитектура загрузки библиотек

В Google Maps JavaScript API функциональность разделена на модули, которые подключаются по требованию. Places Library представляет собой отдельный слой поверх базового JavaScript API карт и предоставляет доступ к геокодированию мест, поиску объектов, автодополнению адресов и расширенным данным о точках интереса.

Подключение библиотек осуществляется через параметр libraries в URL загрузки скрипта. Это позволяет уменьшить начальный вес приложения и загружать только необходимые компоненты.

Базовая структура подключения:

<script
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"
  async
  defer
></script>

Ключевой параметр:

  • libraries=places — активирует Places Library
  • key — API ключ проекта Google Cloud
  • async/defer — асинхронная загрузка без блокировки рендеринга страницы

Подключение через динамическую загрузку

В современных приложениях часто используется динамическая загрузка API через JavaScript вместо прямого подключения скрипта в HTML.

function loadGoogleMapsScript() {
  const script = document.createElement("script");
  script.src =
    "https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places";
  script.async = true;
  script.defer = true;
  document.head.appendChild(script);
}

Такой подход удобен для SPA, где загрузка API зависит от маршрута или пользовательского действия.

Инициализация карты с Places Library

После загрузки API доступен глобальный объект google.maps, внутри которого находятся классы для работы с картами и местами.

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 51.1694, lng: 71.4491 },
    zoom: 12,
  });
}

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

Основные компоненты Places Library

Places Library включает несколько ключевых сервисов:

  • PlacesService — получение информации о местах
  • Autocomplete — автодополнение адресов и объектов
  • AutocompleteService — программный доступ к подсказкам
  • PlaceResult — структура данных о месте
  • Session Tokens — оптимизация биллинга запросов

PlacesService: получение данных о местах

PlacesService используется для запросов к базе мест Google: рестораны, организации, адреса, достопримечательности.

Создание сервиса:

const service = new google.maps.places.PlacesService(map);

Поиск места по текстовому запросу

Метод findPlaceFromQuery выполняет поиск по строке:

const request = {
  query: "Central Park",
  fields: ["name", "geometry", "formatted_address"],
};

service.findPlaceFromQuery(request, (results, status) => {
  if (status === google.maps.places.PlacesServiceStatus.OK) {
    console.log(results);
  }
});

Ключевые поля запроса:

  • query — текст поиска
  • fields — какие данные вернуть (важно для оптимизации стоимости)

Поиск объектов поблизости используется для отображения точек интереса вокруг координаты.

const request = {
  location: { lat: 51.1694, lng: 71.4491 },
  radius: 1500,
  type: "restaurant",
};

service.nearbySearch(request, (results, status) => {
  if (status === google.maps.places.PlacesServiceStatus.OK) {
    results.forEach((place) => {
      console.log(place.name);
    });
  }
});

Параметры:

  • location — центр поиска
  • radius — радиус в метрах
  • type — тип объектов (restaurant, cafe, hospital и т.д.)

Детальная информация о месте (getDetails)

Метод getDetails позволяет получить расширенные данные о конкретном месте.

const request = {
  placeId: "ChIJN1t_tDeuEmsRUsoyG83frY4",
  fields: [
    "name",
    "rating",
    "formatted_phone_number",
    "geometry",
    "opening_hours",
    "website",
  ],
};

service.getDetails(request, (place, status) => {
  if (status === google.maps.places.PlacesServiceStatus.OK) {
    console.log(place);
  }
});

Важно ограничивать fields, так как каждый дополнительный параметр влияет на стоимость запроса.

Autocomplete: автодополнение адресов

Autocomplete позволяет реализовать интеллектуальный ввод адресов и объектов.

const input = document.getElementById("search");

const autocomplete = new google.maps.places.Autocomplete(input, {
  types: ["geocode"],
});

Основные параметры:

  • types — ограничение типов (geocode, address, establishment)
  • componentRestrictions — ограничение по стране

Пример ограничения по стране:

{
  componentRestrictions: { country: "kz" }
}

Обработка выбранного места в Autocomplete

autocomplete.addListener("place_changed", () => {
  const place = autocomplete.getPlace();

  console.log(place.name);
  console.log(place.geometry.location.lat());
  console.log(place.geometry.location.lng());
});

getPlace() возвращает объект PlaceResult, содержащий координаты, адрес и дополнительные поля.

AutocompleteService: серверные подсказки

В отличие от UI-компонента, AutocompleteService используется для кастомных интерфейсов.

const service = new google.maps.places.AutocompleteService();

service.getPlacePredictions(
  { input: "Astana" },
  (predictions, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      console.log(predictions);
    }
  }
);

Это позволяет строить собственные UI-компоненты без использования встроенного input.

Session Tokens и оптимизация стоимости

Places API использует систему сессий для группировки запросов Autocomplete и Place Details.

const sessionToken = new google.maps.places.AutocompleteSessionToken();

Использование:

  • один токен на одну пользовательскую сессию ввода
  • сбрасывается после выбора места
  • снижает стоимость запросов Autocomplete + Details

Пример:

const autocomplete = new google.maps.places.Autocomplete(input, {
  sessionToken: sessionToken,
});

Ограничение и фильтрация результатов

Places Library позволяет фильтровать результаты по типам и регионам:

  • types — тип объекта
  • locationBias — смещение поиска к области
  • locationRestriction — строгие границы поиска

Пример bias:

{
  locationBias: {
    radius: 5000,
    center: { lat: 51.1694, lng: 71.4491 }
  }
}

Объект PlaceResult и структура данных

Результаты запросов возвращают объект PlaceResult, который может включать:

  • name — название
  • geometry — координаты
  • formatted_address — адрес
  • rating — рейтинг
  • opening_hours — часы работы
  • photos — фотографии
  • place_id — уникальный идентификатор

Пример работы с координатами:

const location = place.geometry.location;

const lat = location.lat();
const lng = location.lng();

Работа с фотографиями мест

Places Library позволяет получать изображения объектов через PlacePhoto.

const photoUrl = place.photos[0].getUrl({
  maxWidth: 400,
  maxHeight: 400,
});

Особенности:

  • фотографии требуют place.photos
  • можно ограничивать размер
  • доступ зависит от уровня доступа API

Ограничения и квоты запросов

При работе с Places Library необходимо учитывать:

  • квоты Google Cloud проекта
  • стоимость каждого типа запроса
  • обязательное ограничение fields
  • необходимость API ключа с включёнными сервисами Places API

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

Типичные ошибки интеграции

  • отсутствует libraries=places в URL
  • не включён Places API в Google Cloud Console
  • API ключ ограничен доменами
  • превышение квоты запросов
  • попытка доступа к полям без запроса в fields

Каждая из этих ошибок приводит к статусам вроде REQUEST_DENIED или INVALID_REQUEST.

Сценарий комплексной интеграции

Типичная архитектура использования Places Library включает:

  • Autocomplete для ввода
  • PlacesService.getDetails для получения данных
  • Map Marker для отображения точки
  • nearbySearch для построения окружения

Пример логики:

autocomplete.addListener("place_changed", () => {
  const place = autocomplete.getPlace();

  map.setCenter(place.geometry.location);

  new google.maps.Marker({
    map,
    position: place.geometry.location,
    title: place.name,
  });
});
Оглавление