Place Details запросы

Назначение Place Details

Place Details запрос используется для получения расширенной информации об объекте, найденном через Places API. В отличие от поиска, который возвращает ограниченный набор данных (имя, координаты, place_id), Place Details формирует полную карточку объекта: контактные данные, часы работы, рейтинг, фотографии, отзывы, типы места и множество дополнительных полей.

Place Details является частью Places Library и работает через сервис PlacesService, встроенный в JavaScript API.

Идентификатор place_id как основа запроса

Ключевым параметром любого запроса Place Details выступает place_id.

place_id — стабильный идентификатор, который:

  • уникален для каждого объекта в базе Google Places;
  • не зависит от координат или языка запроса;
  • сохраняется во времени, даже если данные о месте обновляются.

Пример использования place_id:

const placeId = "ChIJN1t_tDeuEmsRUsoyG83frY4";

Инициализация PlacesService

Для выполнения Place Details запроса используется объект PlacesService, который привязывается к карте или DOM-элементу.

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 48.8566, lng: 2.3522 },
  zoom: 13,
});

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

PlacesService может работать даже без отображения карты, если передать пустой div, однако наличие карты обычно используется для контекста и корректной инициализации API.

Метод getDetails

Основной метод для Place Details запросов:

service.getDetails(request, callback);

Структура request:

const request = {
  placeId: "PLACE_ID",
  fields: ["name", "formatted_address", "geometry", "rating", "formatted_phone_number"],
};

Поле fields и оптимизация запросов

Параметр fields критически важен, так как определяет объем возвращаемых данных и стоимость запроса.

Доступные категории полей:

Базовые данные:

  • name
  • place_id
  • types

Контактная информация:

  • formatted_address
  • international_phone_number
  • website

Геометрия:

  • geometry.location
  • geometry.viewport

Оценки и отзывы:

  • rating
  • user_ratings_total
  • reviews

Медиа:

  • photos

Неправильное использование fields приводит к:

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

Пример Place Details запроса

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

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

Структура ответа Place Details

Объект place может содержать:

{
  name: "Название места",
  formatted_address: "Полный адрес",
  geometry: {
    location: LatLng,
    viewport: LatLngBounds
  },
  rating: 4.5,
  user_ratings_total: 1200,
  international_phone_number: "+33 ...",
  website: "https://...",
  opening_hours: {
    open_now: true,
    weekday_text: []
  },
  photos: [],
  reviews: []
}

Работа с отзывами (reviews)

Отзывы возвращаются как массив объектов:

place.reviews.forEach(review => {
  console.log(review.author_name);
  console.log(review.rating);
  console.log(review.text);
});

Каждый отзыв включает:

  • имя автора;
  • текст;
  • рейтинг;
  • временную метку;
  • фото профиля (при наличии).

Важно учитывать, что Google возвращает ограниченное число отзывов, а не полный список.

Обработка фотографий

Массив photos содержит объекты Photo, требующие отдельного запроса URL.

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

Фотографии не передаются напрямую, только через генерацию URL с ограничениями размеров.

Часы работы (opening_hours)

Структура данных:

place.opening_hours.weekday_text
place.opening_hours.open_now

Пример:

if (place.opening_hours?.open_now) {
  console.log("Открыто");
}

Ошибки и статусы ответа

Каждый Place Details запрос возвращает статус:

  • OK — успешный ответ
  • NOT_FOUND — место не найдено
  • INVALID_REQUEST — ошибка параметров
  • OVER_QUERY_LIMIT — превышение лимита
  • REQUEST_DENIED — отказ в доступе
  • UNKNOWN_ERROR — временная ошибка сервера

Обработка статусов:

if (status !== google.maps.places.PlacesServiceStatus.OK) {
  console.error("Ошибка запроса:", status);
}

Асинхронная интеграция и обёртка в Promise

Хотя getDetails использует callback-стиль, его часто оборачивают в Promise:

function getPlaceDetails(service, request) {
  return new Promise((resolve, reject) => {
    service.getDetails(request, (place, status) => {
      if (status === google.maps.places.PlacesServiceStatus.OK) {
        resolve(place);
      } else {
        reject(status);
      }
    });
  });
}

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

const place = await getPlaceDetails(service, request);

Сессионные токены (sessionToken)

Для повышения качества биллинга и группировки запросов используется AutocompleteSessionToken, который связывает Autocomplete и Place Details.

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

Он позволяет:

  • корректно группировать пользовательские действия;
  • снижать стоимость цепочек запросов;
  • повышать релевантность результатов.

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

Place Details подчиняется следующим ограничениям:

  • квоты запросов на проект;
  • тарификация по полям fields;
  • ограничение частоты запросов;
  • зависимость от включённых API (Places API, Maps JavaScript API).

Неправильная организация запросов приводит к:

  • превышению квоты;
  • блокировке ключа;
  • росту затрат.

Типичные сценарии использования

Place Details применяется в системах:

  • отображения карточек организаций;
  • построения каталогов заведений;
  • туристических сервисов;
  • логистических платформ;
  • поиска точек интереса на карте;
  • CRM-систем с геоданными.

Обогащение данных через комбинирование API

Place Details часто используется вместе с:

  • Autocomplete (для поиска);
  • Nearby Search (для списка объектов);
  • Text Search (для текстового поиска).

Типичный поток:

  1. Autocomplete → получение place_id
  2. Place Details → получение полной информации
  3. Отображение карточки объекта

Структурные особенности данных

Данные Place Details не нормализованы как в классических БД. Они:

  • могут отсутствовать частично;
  • зависят от региона;
  • варьируются по типу места;
  • динамически обновляются Google.

Поэтому обработка всегда требует проверки существования полей:

if (place.website) {
  console.log(place.website);
}
Оглавление