Краткий справочник по Maps JavaScript API

Maps JavaScript API – это клиентский веб-API, который позволяет создавать 2D- и 3D-карты на веб-страницах, добавлять маркеры, пользовательскую графику, анимацию и интерактивные слои данных, а также создавать функции, связанные с местоположением, с помощью библиотеки Places.

Maps JavaScript API: основные факты

  • Продукт: Maps JavaScript API.
  • Другие названия: Maps JS API, Maps JS API v3.
  • Категория: Карты
  • Платформа: JavaScript (браузер).
  • Где выполняется: на стороне клиента (в коде приложения или браузера).
  • Стадия запуска: GA
  • Жизненный цикл: активно.
  • Обзор: обзор Maps JavaScript API
  • Регионы: все страны. Доступность функций (например, 3D-карт, информации о дорожном движении, маршрутов и стилей границ) зависит от страны или региона. К платежным адресам в Европейской экономической зоне применяются Условия использования для ЕЭЗ. (подробнее о покрытии)

Когда использовать Maps JavaScript API

Используйте Maps JavaScript API, если:

  • Вам нужна интерактивная 2D- или 3D-карта с пользовательскими маркерами, графикой или слоями данных на веб-странице.
  • Вам нужно показывать местоположение объектов и маршруты их перемещения в реальном времени, используя собственный поток данных, расширенные маркеры и ломаные линии.
  • Вам нужно нарисовать геозоны (круги, многоугольники) и проверить в браузере, попадают ли координаты внутрь них.
  • Вам нужно реализовать клиентский поиск мест, автозаполнение или получение информации о местах в веб-приложении с помощью библиотеки Places.

Не используйте Maps JavaScript API, если:

  • Вам нужно встроить карту с местоположением компании или ссылку на маршрут, не создавая собственный код JavaScript. Используйте вместо него Maps Embed API.
  • Вам нужна только ссылка, которая открывает Google Карты с местоположением, поиском или маршрутами. Используйте URL Карт.
  • Вам нужно отслеживать транспортные средства, которые используются для совместных поездок или доставки по расписанию. Для этого вы интегрировали Driver SDK для мобильных устройств и аутентификацию JWT на сервере. Используйте Fleet Engine Service.

Maps JavaScript API: настройка

Официальные пакеты Maps JavaScript API:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

Maps JavaScript API: распространенные ошибки

  • Проблема. Вместо сообщения об ошибке появляется затемненная карта или негатив изображения Просмотра улиц с графическим водяным знаком "for development purposes only" (только для целей разработки). Это происходит, если ключ API или платежный аккаунт настроены неправильно. Решение. Включите оплату в облачном проекте, добавляйте действительный ключ API в каждый запрос и проверяйте консоль браузера на наличие кода ошибки. Подробнее: /maps/documentation/javascript/error-messages.
  • Проблема. Устаревшие сервисы, такие как PlacesService, DirectionsService и DistanceMatrixService, вызывают ошибку LegacyApiNotActivatedMapError в новых проектах, где устаревший API не включен. Решение. Используйте новые эквиваленты (класс Place, класс Route, класс RouteMatrix), поддерживаемые Places API (New) и Routes API. Подробнее: /maps/legacy#LegacyApiNotActivatedMapError.
  • Проблема. Начиная с версии 3.65 спутниковые и гибридные карты больше не переключаются на изображения под углом 45°, а метод map.setTilt(45) не работает. Решение. Используйте 3D-карты вместо снимков под углом 45°. Подробнее: /maps/deprecations.
  • Проблема. Для расширенных маркеров требуется идентификатор карты. Если карта создана без него, использовать AdvancedMarkerElement нельзя. Решение. Создайте идентификатор карты в Cloud Console (или используйте DEMO_MAP_ID для тестирования) и задайте mapId на карте. Подробнее /maps/documentation/javascript/advanced-markers/start…

Maps JavaScript API: устаревшие и не поддерживаемые функции

  • Directions Service (google.maps.DirectionsService): устаревший с 1 марта 2025 г. Замена: класс Route. Признак. Ошибка LegacyApiNotActivatedMapError в проектах, в которых не включен устаревший Directions API. Ознакомьтесь с руководством по переносу.
  • Сервис «Матрица расстояний» (google.maps.DistanceMatrixService): устаревший с 1 марта 2025 г. Замена: класс RouteMatrix. Признак. Ошибка LegacyApiNotActivatedMapError в проектах, где не включена устаревшая версия Distance Matrix API. Ознакомьтесь с руководством по переносу.
  • Places Service (google.maps.places.PlacesService): устаревшая версия с 1 марта 2025 г. Замена: класс Place (Places API (New)). Признак. Ошибка LegacyApiNotActivatedMapError в проектах, где не включена устаревшая версия Places API. Ознакомьтесь с руководством по переносу.
  • google.maps.Marker: поддержка прекращена 22 февраля 2024 г. Замена: google.maps.marker.AdvancedMarkerElement. Признак. Функция по-прежнему работает, и ее не планируется отключать, но существующие ошибки не будут исправлены. Ознакомьтесь с руководством по переносу.
  • KmlLayer: поддержка прекращена 30 апреля 2026 г. Замена. Стили на основе данных для наборов данных или сторонние синтаксические анализаторы KML со слоем данных. Признак. KmlLayer недоступен в версии 3.66 и более поздних. Версия 3.65, последняя, в которой он поддерживается, будет выведена из эксплуатации в мае 2027 года. Ознакомьтесь с руководством по переносу.
  • Слой тепловых карт (библиотека Visualization): выведен из эксплуатации 20 мая 2026 г. Замена. Сторонние библиотеки, например deck.gl HeatmapLayer. Симптом. Недоступно с мая 2026 г. Ознакомьтесь с руководством по переносу.
  • Библиотека Drawing. Выведена из эксплуатации 4 июня 2026 г. Замена: Terra Draw. Симптом. Недоступно с мая 2026 г. Ознакомьтесь с руководством по переносу.
  • Снимки под углом 45° выведены из эксплуатации 20 мая 2026 г. Замена: 3D-карты. Признак. Метод map.setTilt(45) не работает, вид со спутника остается сверху вниз. Ознакомьтесь с руководством по переносу.
  • google.maps.event.addDomListener() и addDomListenerOnce(). Поддержка прекращена 7 апреля 2022 г. Замена: стандартный DOM addEventListener().
  • Параметры bounds, location и radius в сервисе автозаполнения мест. Поддержка прекращена 18 мая 2023 г. Замена: locationBias и locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) в Places UI Kit: устарело. Замена. Добавьте элементы контента непосредственно в элементы информации о местах или в конфигурацию поиска мест.
  • Библиотека локального контекста: выведена из эксплуатации. Замена: библиотека Places.

Что можно делать с помощью Maps JavaScript API

Ниже приведены ссылки на руководства по каждой задаче. Вы также можете сравнить возможности продуктов в Обзоре возможностей.

Maps JavaScript API: проверка адреса

Maps JavaScript API: стили на основе данных для границ

Maps JavaScript API: стили на основе данных для наборов данных

Maps JavaScript API: наборы данных

  • Добавление слоя KML на карту. Примечание. В Maps JavaScript API класс KmlLayer больше не поддерживается (последняя поддерживаемая версия – 3.65, поддержка прекращена в мае 2027 г.). Перейдите на стили на основе данных для границ или наборов данных или загрузите GeoJSON в слой данных. Слои KML по-прежнему поддерживаются на Android и iOS через библиотеки утилит Maps SDK.
  • Добавление слоя GeoRSS на карту Примечание. Поддержка прекращена в Maps JavaScript API (KmlLayer поддерживается в версии 3.65, будет выведен из эксплуатации в мае 2027 г.). Преобразуйте фиды GeoRSS в GeoJSON и загрузите их в слой данных с помощью map.data.addGeoJson().
  • Добавлять на карту данные GeoJSON.

Maps JavaScript API: маршруты и навигация

Maps JavaScript API: Elevation

Maps JavaScript API: Fleet Engine

Maps JavaScript API: геокодирование

Maps JavaScript API: Maps

Maps JavaScript API: аннотации на картах

Maps JavaScript API: стили карт

Maps JavaScript API: другое

Maps JavaScript API: фотореалистичные трехмерные карты

Maps JavaScript API: Places

Maps JavaScript API: Places UI Kit

Maps JavaScript API: Просмотр улиц