Все готово!

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

Активация Google Maps JavaScript API

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Maps JavaScript API и связанных служб
  3. Создание соответствующих ключей
Продолжить

Обновление вашего приложения с версии Google Maps JavaScript API v2 до версии v3

Версия 2 Google Maps JavaScript API больше не доступна. Настоящее руководство предназначено для разработчиков, которые уже используют Google Maps JavaScript API v2 и переносят свой код на версию 3.

Между версиями Google Maps JavaScript API v2 и v3 есть много отличий. Приступив к работе с новым API, вы быстро обнаружите, что это не просто очередное обновление. Мы добавили много новых полезных функций и улучшили общее удобство использования API с точки зрения разработчика. Если вы планируете перейти с версии Google Maps JavaScript API v2 на версию Google Maps JavaScript API v3, это руководство поможет вам в ходе этого процесса. Также здесь вы найдете описание наиболее распространенных изменений для пользователей API v2.

Обзор

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

  1. Получите новый ключ. Для управления ключами в Google Maps JavaScript API теперь используется Google API Console. Прежде чем начать миграцию, обязательно получите новый ключ API.
  2. Обновите загрузочную строку API. В большинстве приложений Google Maps JavaScript API v3 загружается с помощью следующего кода:
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
  3. Обновите код. Объем требуемых изменений во многом зависит от вашего приложения. Ниже приведены примеры распространенных изменений.
    • Всегда используйте ссылку на пространство имен google.maps. В v3 весь код Google Maps JavaScript API хранится в пространстве имен google.maps.*, а не в глобальном пространстве имен. В связи с этим большинство объектов были переименованы. Например, вместо GMap2 теперь нужно загружать google.maps.Map.
    • Удалите все ссылки на устаревшие методы. Некоторые служебные методы общего назначения, такие как GDownloadURL и GLog, были удалены. Вы можете заменить их функции служебными библиотеками сторонних разработчиков или удалить ссылки на них из своего кода.
    • (Необязательно) Добавьте в свой код библиотеки. Многие функции были перенесены в служебные библиотеки, чтобы каждому приложению нужно было загружать только те части API, которые оно использует.
    • (Необязательно) Настройте свой проект для использования внешних методов v3. Внешние методы v3 можно использовать для проверки кода с помощью инструмента Closure Compiler или для активации подсказки мест в среде разработки. Узнайте больше о расширенной компиляции и внешних методах.
  4. Проведите тестирование и повторное тестирование. Вам еще осталось кое-что сделать, но вы уже значительно продвинулись в миграции вашего приложения на версию v3!

Изменения в Google Maps JavaScript API версии 3

Прежде чем планировать миграцию, вам нужно понять различия между Google Maps JavaScript API v2 и Google Maps JavaScript API v3. Последняя версия Google Maps JavaScript API была создана с нуля на основе современных методик программирования JavaScript, расширенного использования библиотек и упрощенного API. В API добавлено много новых функций, а некоторые привычные функции были изменены или даже удалены. В этом разделе описываются некоторые ключевые отличия между двумя версиями.

Ниже приведены некоторые из изменений в API v3.

  • Оптимизированная базовая библиотека. Многие дополнительные функции перемещены в библиотеки, чтобы сократить нагрузку и время синтаксического анализа для Core API, обеспечивая быструю загрузку карт на любом устройстве.
  • Повышена производительность ряда функций, например, прорисовки многоугольников и размещения маркеров.
  • Новый подход к лимитам использования на стороне клиента больше оптимизирован для общих адресов, используемых прокси-серверами мобильных операторов и корпоративными брандмауэрами.
  • Добавлена поддержка нескольких современных браузеров для компьютеров и мобильных устройств. Удалена поддержка Internet Explorer 6.
  • Удалены многие вспомогательные классы общего назначения (такие как GLog или GDownloadUrl). Сегодня существует множество отличных библиотек JavaScript, предоставляющих те же функции, например, Closure и jQuery.
  • Реализация Street View в HTML5, которая будет загружаться на любом мобильном устройстве.
  • Пользовательские панорамы Street View с вашими собственными фотографиями, которые позволяют вам делиться панорамами лыжных спусков, домов на продажу и других интересных мест.
  • Настраиваемые стилизованные карты, которые позволяют изменять отображение элементов на базовой карте в соответствии с вашим уникальным стилем.
  • Поддержка нескольких новых служб, в том числе Elevation и Distance Matrix.
  • Улучшенная служба Directions предоставляет альтернативные маршруты, оптимизацию маршрутов (приближенные решения задачи коммивояжера), велосипедные маршруты (со слоем велосипедного транспорта), маршруты на общественном транспорте и перетаскиваемые маршруты.
  • Обновленный формат геокодирования предоставляет более точную информацию, используя параметр type вместо значения accuracy из Google Maps Geocoding API v2.
  • Поддержка нескольких информационных окон на отдельной карте.

Обновление вашего приложения

Ваш новый ключ

В Google Maps JavaScript API v3 используется новая система ключей. Это означает, что ключ версии v2 не будет работать с приложениями, использующими версию v3. Добавление ключа v3 перед развертыванием приложения в производственной среде откроет следующие возможности:

Ключ передается при загрузке Google Maps JavaScript API v3. Генерирование ключа:

  1. Перейдите в Google API Console и выполните вход с помощью своей учетной записи Google.
  2. Нажмите ссылку Services в левом меню и активируйте службу Google Maps JavaScript API v3.
  3. После активации службы ваш ключ API будет доступен на странице API Access в разделе Simple API Access. Приложения Maps API используют ключ для приложений браузера.

Идентификаторы клиента для лицензий на Maps APIs for Work

Если вы используете лицензию на Google Maps APIs for Work, вам потребуется идентификатор клиента вместо ключа. Ключ и идентификатор нельзя использовать вместе. Идентификаторы клиента похожи на ключи, но имеют следующие отличия:

  • Приложения Google Maps APIs, использующие идентификатор клиента, имеют доступ к дополнительным функциям и лимитам, например, к инструменту Maps Analytics.
  • Ваш идентификатор клиента создается Google Cloud Support и предоставляется вам в письме о регистрации Maps APIs for Work. Для создания или поиска идентификатора клиента не нужно использовать Google API Console.
  • При загрузке Google Maps JavaScript API нужно использовать параметр client вместо параметра key. Например: 
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>

    • Идентификаторы клиента всегда имеют префикс gme-.

Загрузка API

Первое изменение, которое вам потребуется внести в код своего приложения, связано с методом загрузки API. В версии v2 загрузка Google Maps JavaScript API выполнялась посредством запроса к http://maps.google.com/maps. Для загрузки Google Maps JavaScript API v3 нужно внести следующие изменения:

  1. Загружайте API с адреса //maps.googleapis.com/maps/api/js.
  2. Удалите параметр file.
  3. Добавьте обязательный параметр sensor.
  4. Обновите параметр key, указав свой новый ключ v3. Пользователи Google Maps APIs for Work должны использовать параметр client.
  5. (только для Google Maps APIs Premium Plan) Убедитесь, что указан параметр client, как описано в руководстве для разработчиков по Google Maps APIs Premium Plan.
  6. Удалите параметр v, чтобы запрашивать последнюю выпущенную версию, или измените его в соответствии со схемой обозначения версий v3.
  7. (Необязательно) Замените параметр hl параметром language и сохраните его значение.
  8. (Необязательно) Добавьте параметр libraries для загрузки дополнительных библиотек.

В самом простом случае в загрузочной строке v3 будут указаны только ключ API и параметр sensor:

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=false"></script>

Для примера ниже требуется последняя (экспериментальная) версия Maps JavaScript API v2 на немецком языке:

<script type="text/javascript" src="//maps.google.com/maps?file=api&v=2.x&sensor=false&key=YOUR_API_KEY&hl=de"></script>

В примере ниже показан эквивалентный запрос для v3.

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

Определение версии

В v3 не требуется загрузка определенной версии. Если вы пропустите параметр version, вы получите последнюю экспериментальную версию API. По желанию вы можете указать конкретный номер версии, последнюю (экспериментальную) версию или самую стабильную зафиксированную версию.

В таблице ниже показано соответствие схем обозначения для v2 и v3.

v2 v3 Вариант использования
2.s 3.0 Зафиксированная версия. Самая старая доступная версия.
2 3 Выпущенная версия. Последняя стабильная версия.
2.x 3.exp Экспериментальная версия.

Внимание! Соглашение об уровне обслуживания Google Maps APIs Premium Plan не действует в отношении экспериментальной версии. Для применения Соглашения об уровне обслуживания в приложениях должна использоваться текущая выпущенная или зафиксированная версия Google Maps APIs Premium Plan.

Введение пространства имен google.maps

Наиболее заметное изменение Google Maps JavaScript API v3 – добавление пространства имен google.maps. По умолчанию API v2 помещает все объекты в пространство имен Global, что может привести к возникновению конфликтов имен. В версии v3 все объекты располагаются в пространстве имен google.maps.

При переносе приложения на версию v3 необходимо изменить программный код для использования нового пространства имен. К сожалению, простая операция поиска и замены "G" на "google.maps." поможет не полностью, но будет полезной при проверке кода. Ниже приведены несколько примеров эквивалентных классов в версиях v2 и v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
или google.maps.PolylineOptions

Удаление устаревшего кода

Функции Google Maps JavaScript API v3 во многом совпадают с функциями v2, однако некоторые классы больше не поддерживаются. В рамках миграции нужно заменить эти классы служебными библиотеками сторонних разработчиков или удалить эти ссылки из вашего кода. Существует множество отличных библиотек JavaScript, предоставляющих те же функции, например, Closure или jQuery.

У следующих классов нет аналогов в Google Maps JavaScript API v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Сравнение кода

Давайте сравним два простых приложения, написанных с помощью API v2 и v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Как видите, между двумя приложениями есть некоторые отличия. Некоторые заметные изменения:

  • Изменился адрес загрузки API.
  • Методы GBrowserIsCompatible() и GUnload() больше не требуются в v3 и были удалены из API.
  • Объект GMap2 заменен на google.maps.Map в качестве центрального объекта API.
  • Свойства теперь загружаются через классы Options. В вышеуказанном примере мы устанавливаем три свойства, требующиеся для загрузки карты – center, zoom и mapTypeId – с помощью встроенного объекта MapOptions.
  • Пользовательский интерфейс по умолчанию включен в версии v3. Вы можете отключить его, установив для свойства disableDefaultUI объекта MapOptions значение true.

Сводная информация

Сейчас вы немного узнали о некоторых основных аспектах миграции с версии Google Maps JavaScript API v2 на версию Google Maps JavaScript API v3. Вам может потребоваться намного больше информации, но это зависит от вашего приложения. В следующих разделах мы добавили инструкции по миграции для определенных случаев, с которыми вы можете столкнуться. Кроме того, имеется ряд ресурсов, которые могут оказаться вам полезными в процессе обновления.

Если у вас возникнут проблемы или вопросы по этой статье, используйте ссылку Send Feedback в верхней части этой страницы.

Подробная справка

В этом разделе содержится подробное сравнение наиболее популярных функций Google Maps JavaScript API версий 2 и 3. С каждым разделом справочника можно ознакомиться отдельно. Мы рекомендуем не читать справочник целиком, а использовать эти материалы для решения конкретных задач во время миграции.

  • События – регистрация и обработка событий.
  • Элементы управления – манипуляции с навигационными элементами управления, которые отображаются на карте.
  • Наложения – добавление и редактирование объектов на карте.
  • Типы карт – фрагменты, составляющие основную карту.
  • Слои – добавление и редактирование групп контента, например, слоев KML или дорожной обстановки.
  • Службы – работа со службами Geocoding, Directions или Street View.

События

Модель событий Google Maps JavaScript API v3 похожа на модель, используемую в v2, хотя в ней произошло много внутренних изменений.

Элементы управления

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

Наложения

Наложения соответствуют объектам, которые "добавляются" на карту для обозначения точек, линий, областей и наборов объектов.

Типы карт

Доступные в v2 и v3 типы карт немного различаются, однако в обоих версиях API доступны все базовые типы карт. По умолчанию в v2 используются стандартные "окрашенные" фрагменты дорожной карты. Однако в v3 при создании объекта google.maps.Map нужно указать определенный тип карты.

Слои

Слои – это объекты на карте, состоящие из одного или нескольких наложений. С ними можно совершать операции как с одним элементом, и обычно они представляют собой наборы объектов.

Службы

Оставить отзыв о...

Текущей странице
Документации
Google Maps JavaScript API
Google Maps JavaScript API
Продуктах
Нужна помощь? Обратитесь в службу поддержки.