KML (Keyhole Markup Language) представляет собой XML-формат, предназначенный для описания географических данных: точек, линий, полигонов, а также сложных структур вроде маршрутов, областей интереса и слоёв с метаданными. В контексте Google Maps JavaScript API KML-слои позволяют отображать заранее подготовленные геоданные поверх интерактивной карты без необходимости ручного построения геометрии через JavaScript.
KML-слой выступает как абстракция между картографическим движком и внешним источником данных, где сама карта отвечает за визуализацию, а KML-файл — за структуру и содержание данных.
Основной механизм работы с KML реализован через класс
google.maps.KmlLayer.
const map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 48.0, lng: 66.9 },
zoom: 5,
});
const kmlLayer = new google.maps.KmlLayer({
url: "https://example.com/data/map.kml",
map: map,
});Ключевой параметр — url, указывающий на публично
доступный KML-файл. Доступность по HTTP(S) критична: локальные файлы и
приватные ресурсы без корректных заголовков не будут обработаны.
При работе с KML-слоями накладываются строгие ограничения:
Эти ограничения определяют архитектурный подход: KML-слои чаще используются как «read-only» визуализация внешних данных.
Конфигурация слоя задаётся через объект параметров:
const kmlLayer = new google.maps.KmlLayer({
url: "https://example.com/data.kml",
suppressInfoWindows: false,
preserveViewport: true,
map: map,
});Определяет поведение информационных окон:
false — стандартные окна отображаются при клике на
объекты;true — подавление встроенных popup-окон, что полезно
при кастомной обработке событий.Управляет автоматическим масштабированием карты:
true — карта не изменяет текущий viewport при загрузке
слоя;false — карта автоматически подстраивается под границы
KML.KML-слои генерируют события, которые позволяют отслеживать взаимодействие пользователя с геообъектами.
kmlLayer.addListener("click", (event) => {
console.log(event.latLng);
console.log(event.featureData.name);
});Событие click предоставляет доступ к метаданным
объекта:
Объект события содержит featureData, включающий:
name — имя объекта;description — HTML-описание;author — автор KML (если указан);snippet — краткое описание;infoWindowHtml — готовая HTML-разметка для
InfoWindow.Эти данные формируются на стороне сервиса обработки KML и не требуют ручного парсинга XML.
KMZ представляет собой архивированный KML-файл с ресурсами (иконки, изображения, вложенные файлы). Поддержка KMZ в KmlLayer позволяет:
Структурно KMZ остаётся ограниченным форматом: логика взаимодействия не расширяется относительно KML.
KML-слои поддерживают стандартные геометрические типы:
Отображаются как маркеры на карте. Стиль может задаваться через KML:
<Point>
<coordinates>66.9237,48.0196,0</coordinates>
</Point>Используются для маршрутов и трасс:
<LineString>
<coordinates>
66.9,48.0,0 67.1,48.2,0
</coordinates>
</LineString>Применяются для областей и зон:
<Polygon>
<outerBoundaryIs>
<LinearRing>
<coordinates>...</coordinates>
</LinearRing>
</outerBoundaryIs>
</Polygon>KML поддерживает декларативную стилизацию:
Пример стиля:
<Style id="blueLine">
<LineStyle>
<color>ff0000ff</color>
<width>4</width>
</LineStyle>
</Style>В Google Maps JavaScript API стили из KML применяются автоматически и не требуют переопределения в JavaScript.
Параметр preserveViewport напрямую влияет на поведение
карты:
false карта центрируется по bounding box KML;true текущая позиция пользователя сохраняется.В случаях многослойной визуализации фиксирование viewport критично для предотвращения конфликтов между слоями.
Несколько слоёв могут быть добавлены одновременно:
const layer1 = new google.maps.KmlLayer({ url: "a.kml", map });
const layer2 = new google.maps.KmlLayer({ url: "b.kml", map });Особенности взаимодействия:
KML-слои обрабатываются серверной инфраструктурой Google, что снижает нагрузку на клиент, но вводит ограничения:
Архитектурно KML лучше использовать для статических или редко изменяемых данных.
KML-слои загружаются по URL, что создаёт зависимость от внешнего источника:
KML-слои часто комбинируются с другими механизмами карты:
google.maps.Marker);google.maps.Polygon);HeatmapLayer);При наложении слоёв KML обычно выступает как базовый слой данных, поверх которого строится интерактивная логика приложения.
KML-слой в Google Maps JavaScript API является высокоуровневой абстракцией, поэтому:
click.KML-слои применяются для:
Каждый сценарий опирается на неизменяемость данных и централизованное управление KML-файлом.
При недоступности KML-файла или некорректной структуре события загрузки могут не инициироваться. Для отслеживания состояния используется:
kmlLayer.addListener("status_changed", () => {
console.log(kmlLayer.getStatus());
});Типичные статусы включают ошибки загрузки, некорректный формат или превышение лимитов.
Интерпретация KML осуществляется не браузером напрямую, а сервисом обработки геоданных. Это означает:
KML-слои занимают промежуточное положение между статическими данными и динамическими API-объектами. Их использование снижает сложность клиентской логики, но переносит ответственность за структуру данных на внешние источники.
В экосистеме Google Maps JavaScript API они выполняют функцию интеграционного слоя для геоданных, поступающих из GIS, аналитических систем и сторонних картографических сервисов.