Street View Service

Google Maps JavaScript API предоставляет специализированный набор инструментов для работы со Street View через объектную модель Street View Service. Эта часть API отвечает за получение панорамных изображений улиц, управление виртуальной камерой и интеграцию панорам в пользовательские интерфейсы веб-приложений.

Street View в JavaScript API построен вокруг трёх ключевых компонентов:

  • StreetViewService — поиск доступных панорамных данных
  • StreetViewPanorama — визуализация и управление панорамой
  • Street View Events — обработка изменений состояния панорамы

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

StreetViewService: получение панорамных данных

StreetViewService используется для запроса ближайших панорамных изображений по координатам или параметрам поиска.

Основной метод: getPanorama

const service = new google.maps.StreetViewService();

service.getPanorama(
  {
    location: { lat: 43.238949, lng: 76.889709 },
    radius: 50
  },
  (data, status) => {
    if (status === "OK") {
      console.log("Pano ID:", data.location.pano);
    }
  }
);

Параметры запроса

  • location — координаты точки поиска
  • radius — радиус поиска в метрах
  • source — источник данных (default / outdoor)

Статусы ответа

  • OK — панорама найдена
  • ZERO_RESULTS — нет доступных панорам
  • UNKNOWN_ERROR — ошибка сервера
  • INVALID_REQUEST — некорректные параметры

StreetViewPanorama: визуализация панорамы

StreetViewPanorama отвечает за отображение 360° изображения и управление камерой.

Инициализация панели

const panorama = new google.maps.StreetViewPanorama(
  document.getElementById("street-view"),
  {
    position: { lat: 43.238949, lng: 76.889709 },
    pov: {
      heading: 165,
      pitch: 0
    },
    zoom: 1
  }
);

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

position

Определяет координаты текущей точки обзора.

pov (Point of View)

POV управляет виртуальной камерой:

pov: {
  heading: 90,
  pitch: 10
}
  • heading — направление (0–360°)
  • pitch — вертикальный угол обзора

zoom

Масштаб приближения панорамы.

visible

Управляет отображением Street View слоя.

Управление панорамой программно

StreetViewPanorama предоставляет методы для динамического управления состоянием:

setPosition

panorama.setPosition({ lat: 43.238949, lng: 76.889709 });

setPov

panorama.setPov({
  heading: 200,
  pitch: 5
});

setVisible

panorama.setVisible(true);

getPano

Возвращает идентификатор текущей панорамы:

const panoId = panorama.getPano();

События Street View

Система событий позволяет отслеживать изменения состояния панорамы.

Основные события

position_changed

Срабатывает при изменении координат.

panorama.addListener("position_changed", () => {
  console.log(panorama.getPosition());
});

pov_changed

Срабатывает при изменении угла обзора.

panorama.addListener("pov_changed", () => {
  console.log(panorama.getPov());
});

pano_changed

Смена идентификатора панорамы.

panorama.addListener("pano_changed", () => {
  console.log(panorama.getPano());
});

Обновление доступных переходов между панорамами.

status_changed

Изменение статуса загрузки данных Street View.

Навигация между панорамами

Street View поддерживает перемещение между связанными панорамами через links.

panorama.addListener("links_changed", () => {
  const links = panorama.getLinks();
  links.forEach(link => {
    console.log(link.description, link.heading);
  });
});

Каждый link содержит:

  • pano — ID следующей панорамы
  • heading — направление перехода
  • description — текстовое описание

Работа с Street View в Map-интеграции

Street View может быть встроен в карту через Map instance.

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 43.238949, lng: 76.889709 },
  zoom: 14,
  streetViewControl: true
});

const panorama = map.getStreetView();
panorama.setPosition({ lat: 43.238949, lng: 76.889709 });
panorama.setPov({ heading: 100, pitch: 0 });
panorama.setVisible(true);

Street View автоматически синхронизируется с картой при включённом контроле.

Street View Service и поиск ближайшей панорамы

Часто используется сценарий «найти ближайшую доступную панораму»:

const service = new google.maps.StreetViewService();

service.getPanorama(
  {
    location: { lat: 43.238949, lng: 76.889709 },
    radius: 100
  },
  (result, status) => {
    if (status === "OK") {
      panorama.setPano(result.location.pano);
      panorama.setPov({ heading: 0, pitch: 0 });
    }
  }
);

Объект StreetViewLocation

Результат запроса содержит структурированную информацию:

{
  location: {
    pano: "abc123",
    description: "Street name",
    latLng: { lat: 43.238, lng: 76.889 }
  },
  copyright: "© Google",
  links: []
}

Эта структура используется для точной идентификации панорамы и её связей.

Настройки поведения Street View

StreetViewPanoramaOptions включает расширенные параметры:

disableDefaultUI

Отключает стандартные элементы управления.

showRoadLabels

Управляет отображением подписей дорог.

clickToGo

Разрешает переход по клику на карту.

const panorama = new google.maps.StreetViewPanorama(
  container,
  {
    clickToGo: true,
    disableDefaultUI: false,
    showRoadLabels: true
  }
);

Интеграция с кастомными интерфейсами

Street View может использоваться как backend для собственной визуализации:

panorama.addListener("pov_changed", () => {
  const pov = panorama.getPov();
  updateCompass(pov.heading);
});

или

panorama.addListener("position_changed", () => {
  syncMarker(panorama.getPosition());
});

Работа с идентификаторами панорам (Pano ID)

Каждая панорама имеет уникальный идентификатор:

  • используется для прямой загрузки
  • позволяет кешировать состояние
  • применяется при навигации между точками
panorama.setPano("unique_pano_id");

Ограничения и особенности поведения

Street View Service зависит от покрытия:

  • доступность данных варьируется по регионам
  • radius влияет на вероятность результата
  • outdoor source ограничивает внутренние помещения

При отсутствии данных сервис возвращает ZERO_RESULTS, даже если координаты корректны.

Связь Street View с визуальными слоями карты

Street View не является просто слоем карты, а отдельной системой рендеринга. Однако он синхронизируется с Map API через:

  • shared state position
  • shared controls
  • linked camera system

Это позволяет создавать комбинированные интерфейсы «карта + панорама» с динамической связью движения и ориентации.

Оглавление