Подключение библиотеки к странице

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

Перед использованием любого функционала необходимо правильно подключить библиотеку к странице. Именно на этапе подключения выполняется загрузка кода API, инициализация необходимых модулей и авторизация приложения через API-ключ.

Предварительные требования

Для подключения Google Maps JavaScript API необходимо:

  • иметь аккаунт Google;
  • создать проект в Google Cloud Console;
  • включить Google Maps JavaScript API;
  • получить API-ключ;
  • настроить ограничения доступа к ключу.

Без API-ключа библиотека работать не будет.

Типичная последовательность действий:

  1. Создание проекта в Google Cloud.
  2. Подключение платежного аккаунта.
  3. Активация Google Maps JavaScript API.
  4. Генерация API Key.
  5. Настройка ограничений безопасности.
  6. Подключение библиотеки на страницу.

Получение API-ключа

После создания проекта в Google Cloud необходимо перейти в раздел управления API и создать новый ключ доступа.

Пример ключа:

AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Реальный ключ всегда уникален и привязывается к конкретному проекту.

Для повышения безопасности рекомендуется ограничить использование ключа по доменам:

https://example.com/*
https://www.example.com/*

Такой подход предотвращает использование ключа сторонними сайтами.

Классический способ подключения через тег script

Самый распространённый вариант подключения выполняется через HTML-тег <script>.

Пример:

<script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
</script>

После загрузки скрипта в браузере становится доступно глобальное пространство имён:

google.maps

Через него осуществляется работа со всеми объектами API.

Например:

console.log(google.maps);

Подключение с использованием callback-функции

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

Для этого используется параметр callback.

Пример:

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

Функция инициализации:

function initMap() {
    console.log("Google Maps загружен");
}

После завершения загрузки библиотеки Google автоматически вызовет функцию initMap().

Схема работы выглядит следующим образом:

Загрузка страницы
        ↓
Загрузка Google Maps API
        ↓
Вызов callback-функции
        ↓
Создание карты

Назначение атрибутов async и defer

При подключении внешнего скрипта рекомендуется использовать атрибуты:

async
defer

Полный пример:

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

Атрибут async

Позволяет загружать файл параллельно с построением HTML-документа.

Без него браузер приостанавливает обработку страницы до окончания загрузки скрипта.

Атрибут defer

Откладывает выполнение скрипта до завершения разбора HTML.

Благодаря этому элементы страницы гарантированно существуют к моменту запуска JavaScript-кода.

Создание контейнера для карты

Перед инициализацией карты необходимо создать HTML-элемент, в котором она будет отображаться.

Пример:

<div id="map"></div>

Задание размеров:

#map {
    width: 100%;
    height: 500px;
}

Если высота контейнера не задана, карта отображаться не будет.

Типичная ошибка:

#map {
    width: 100%;
}

В этом случае высота равна нулю.

Полный пример подключения библиотеки

HTML:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">

    <style>
        #map {
            width: 100%;
            height: 500px;
        }
    </style>
</head>
<body>

<div id="map"></div>

<script>
function initMap() {
    const map = new google.maps.Map(
        document.getElementById("map"),
        {
            center: {
                lat: 55.7558,
                lng: 37.6176
            },
            zoom: 10
        }
    );
}
</script>

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

</body>
</html>

После загрузки страницы будет отображена карта, центрированная на Москве.

Подключение дополнительных библиотек

Google Maps предоставляет набор вспомогательных модулей.

Для подключения используется параметр libraries.

Пример:

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

Подключение нескольких библиотек:

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

Наиболее востребованные библиотеки:

Библиотека Назначение
places Поиск мест и автодополнение
geometry Геометрические вычисления
drawing Рисование объектов
visualization Тепловые карты
marker Расширенные маркеры

Современный способ подключения через importLibrary

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

Подключение:

<script>
(g => {
    var h, a, k, p = "The Google Maps JavaScript API",
    c = "google",
    l = "importLibrary",
    q = "__ib__",
    m = document,
    b = window;

    b = b[c] || (b[c] = {});
    var d = b.maps || (b.maps = {}),
        r = new Set,
        e = new URLSearchParams;

    const u = () =>
        h || (h = new Promise(async (f, n) => {
            a = m.createElement("script");

            e.set("key", "YOUR_API_KEY");
            e.set("v", "weekly");

            a.src =
                `https://maps.googleapis.com/maps/api/js?` +
                e;

            d[q] = f;
            a.oner ror = () =>
                h = n(Error(p + " could not load."));

            a.nonce =
                m.querySelector("script[nonce]")?.nonce || "";

            m.head.append(a);
        }));

    d[l]
        ? console.warn(p + " only loads once.")
        : d[l] = (f, ...n) =>
            r.add(f) && u().then(() => d[l](f, ...n));

})({
    key: "YOUR_API_KEY",
    v: "weekly"
});
</script>

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

Пример:

async function initMap() {

    const { Map } =
        await google.maps.importLibrary("maps");

    const map = new Map(
        document.getElementById("map"),
        {
            center: {
                lat: 55.7558,
                lng: 37.6176
            },
            zoom: 12
        }
    );
}

Преимущества подхода:

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

Указание версии библиотеки

Версия API задаётся параметром v.

Пример:

<script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=weekly">
</script>

Доступные варианты:

Значение Описание
weekly Последняя стабильная версия
beta Бета-версия
alpha Экспериментальная версия
quarterly Обновление раз в квартал

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

<script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=quarterly">
</script>

Обработка ошибок загрузки

Иногда библиотека не загружается из-за:

  • неверного API-ключа;
  • превышения квот;
  • блокировки домена;
  • отсутствия доступа к интернету;
  • отключённого API в проекте.

Пример проверки:

window.gm_authFailure = function () {
    console.error("Ошибка авторизации Google Maps");
};

Если авторизация завершится неудачно, будет вызвана функция gm_authFailure.

Проверка успешной загрузки API

После подключения можно убедиться, что библиотека доступна.

Пример:

if (window.google && window.google.maps) {
    console.log("API успешно загружен");
}

Или:

console.log(typeof google.maps);

Результат:

object

Использование API в модульных приложениях

При работе с современными сборщиками проектов (Webpack, Vite, Parcel) загрузка обычно выполняется после создания интерфейса приложения.

Пример:

async function loadMap() {

    const { Map } =
        await google.maps.importLibrary("maps");

    return new Map(
        document.getElementById("map"),
        {
            center: {
                lat: 55.7558,
                lng: 37.6176
            },
            zoom: 8
        }
    );
}

Такой подход хорошо сочетается с архитектурой SPA-приложений на React, Vue и Angular.

Типичные ошибки при подключении

Карта не отображается

Причина:

#map {
    height: 0;
}

Решение:

#map {
    height: 500px;
}

Неверный API-ключ

Сообщение:

InvalidKeyMapError

Причина:

key=12345

Решение — использовать действительный API Key.

API не включён в проекте

Сообщение:

ApiNotActivatedMapError

Необходимо активировать Google Maps JavaScript API в настройках проекта Google Cloud.

Запросы блокируются ограничениями

Сообщение:

RefererNotAllowedMapError

Причина:

example.com

не указан в списке разрешённых доменов.

Требуется добавить домен в настройки ключа.

Callback-функция отсутствует

Сообщение:

initMap is not a function

Причина:

callback=initMap

при отсутствии самой функции:

function initMap() {}

Необходимо определить функцию до момента её вызова.

Рекомендуемая схема подключения

Для современных проектов оптимальной считается следующая конфигурация:

<div id="map"></div>

<script>
async function initMap() {

    const { Map } =
        await google.maps.importLibrary("maps");

    new Map(
        document.getElementById("map"),
        {
            center: {
                lat: 55.7558,
                lng: 37.6176
            },
            zoom: 10
        }
    );
}
</script>

<script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap&v=weekly"
    async>
</script>

Такая схема обеспечивает актуальную версию API, асинхронную загрузку библиотеки, корректную инициализацию карты и совместимость с современными возможностями Google Maps JavaScript API.

Оглавление