Google Timeline Viewer — инструкция по использованию

Версия программы: 4C.5 · автономное веб-приложение для анализа Google Timeline

Спасибо, Claude Sonnet 5.5 Medium

1. Назначение и возможности

Timeline Viewer открывается в браузере и разбирает выгрузки Google Timeline (и треки KML) прямо на вашем компьютере. Файлы никуда не отправляются: вся обработка идёт локально в браузере. Из сети загружаются только тайлы (картинки) подложки карты.

Что умеет программа:

• читать три вида файлов: новый Timeline.json (с semanticSegments), старый Records.json (с locations) и .kml;
• рисовать маршруты линиями, цвет которых зависит от типа активности (ходьба, велосипед, авто, поезд, самолёт и т. д.);
• показывать посещённые места маркерами, размер которых растёт с числом визитов;
• подсвечивать аномалии скорости красными точками;
• считать статистику: километры, часы по типам активности, число точек, дней и мест, топ мест по времени;
• фильтровать данные по периоду дат и по типам активности;
• переключать светлую и тёмную тему вместе с подложкой карты;
• показывать при наведении на линию маршрута или точку аномалии подсказку с датой и временем в формате ДД.ММ.ГГГГ ЧЧ:мм;
• при узком периоде (до 14 дней) рисовать маршруты без упрощения, с максимальной детализацией.

• показывать тепловую карту мест пребывания (визиты и точки с неизвестной активностью) вместо остальных слоёв, с переключателем в боковой панели.

Не поддерживается: .kmz (сначала распакуйте архив и загрузите doc.kml из него) и другие форматы, кроме перечисленных выше.

2. Запуск

Открывать index.html двойным кликом (адрес file://...) нельзя. Приложение построено на ES-модулях, а браузеры не загружают их по протоколу file://. Страница при этом выглядит нормально, но JavaScript не выполняется: не работают ни выбор файла, ни перетаскивание, ни карта. Папку проекта нужно раздавать через любой локальный веб-сервер.

Вариант 1. Сервер Python (самый простой)

В терминале перейдите в папку timeline-viewer и выполните:

python3 -m http.server 8080

На Windows команда может называться py -m http.server 8080. Затем откройте в браузере http://localhost:8080/index.html.

Чтобы страница была доступна только с вашего компьютера, добавьте --bind 127.0.0.1:

python3 -m http.server 8080 --bind 127.0.0.1

Если после обновления проекта в шапке осталась старая версия или новые функции не работают, браузер отдаёт закэшированные файлы. Запускайте проект сервером без кэша, который лежит в папке проекта:

python3 serve.py

Адрес тот же: http://localhost:8080/index.html. Другой порт: python3 serve.py 9000; доступ из локальной сети (только в доверенной сети): python3 serve.py 8080 0.0.0.0. Прежний python3 -m http.server перед этим остановите, иначе порт будет занят. После смены версии один раз обновите страницу с очисткой кэша (Ctrl+Shift+R). Версию видно в шапке страницы и в консоли браузера (F12): при запуске пишется строка [TimelineViewer] Timeline Viewer v4C.5 запущен.

Вариант 2. Node.js

npx serve .

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

Вариант 3. Расширение для редактора

В VS Code подойдёт расширение Live Server: правый клик по index.html, затем «Open with Live Server».

Вариант 4. Свой веб-сервер (nginx, Caddy и др.)

Укажите папку timeline-viewer как корень сайта. Для работы нужна обычная раздача статических файлов, никакой серверной логики программа не использует.

Признак правильного запуска: адрес в браузере начинается с http:// (или https://), а не с file://.

3. Работа с программой

1. Перетащите файл (или несколько) в область «Перетащите файл(ы) Timeline» либо кликните по ней и выберите файл вручную.
2. После загрузки в верхней строке появится статус: число точек и распознанный формат.
3. На карте отобразятся маршруты, места и аномалии, а слева — статистика и список мест.
4. Сузьте данные фильтрами: период «от — до» и флажки типов активности. Кнопка «Сбросить фильтры» возвращает всё как было.
5. Клик по месту в списке приближает карту к нему. Наведение на линию или красную точку показывает подсказку.
6. Кнопка ☾/☀ в правом верхнем углу переключает тему. Выбор запоминается.

7. Переключатель «Тепловая карта мест пребывания» (блок «Слои карты») заменяет маршруты и маркеры тепловой картой по визитам и точкам UNKNOWN. При выключении фильтры сбрасываются.

4. Что отображается для разных форматов

4.1. Новый формат JSON (Timeline.json, semanticSegments)

Это выгрузка Google Timeline с телефона, самый полный формат.

• Маршруты — линии, цвет по типу активности. Если у сегмента есть timelinePath, линия идёт по всем его точкам. Если пути нет, но есть начало и конец активности, рисуется прямая линия между ними.
• Сегменты без activity, у которых есть только timelinePath, тоже рисуются, но с типом UNKNOWN: типа активности в файле просто нет.
• Места — желтые маркеры по визитам (visit). Близкие визиты в радиусе 150 м объединяются в одно место, в расчёт идут визиты от 5 минут. В подсказке видны тип места (Home, Work и т. п.), число визитов и суммарное время.
• Дистанция берётся из distanceMeters самого сегмента; если его нет, считается по точкам.
• Фильтр по типам активности заполняется реальными типами из файла.
• Предупреждения показываются после загрузки, если какие-то сегменты не удалось разобрать.

4.2. Старый формат JSON (Records.json, locations)

Это сырой поток GPS-замеров без готовых сегментов и визитов.

• Программа собирает сегменты сама, объединяя подряд идущие точки с одинаковым типом активности.
• В большинстве современных выгрузок поля активности нет. Тогда весь трек превращается в один сегмент UNKNOWN, а в фильтрах будет один флажок.
• Линия соединяет точки подряд, поэтому на больших разрывах во времени и пространстве появятся длинные прямые «перемычки».
• Мест нет: в старом формате нет понятия визита, поэтому список мест будет пустым.
• Файлы бывают очень большими (сотни тысяч точек). Загрузка и отрисовка могут занимать заметное время. Узкий период в фильтре заметно ускоряет работу.
• Аномалий скорости в таких данных обычно много: GPS «прыгает».

4.3. KML (.kml)

Поддерживаются три вида элементов внутри Placemark:

• gx:Track — самый точный вариант: у каждой точки своё время. Рисуется как маршрут. Тип активности угадывается по названию Placemark (например, «пробежка» даёт бег, «bike» даёт велосипед); если подсказки нет, тип будет UNKNOWN.
• LineString — линия без времени на точках. Если у Placemark есть TimeSpan, время равномерно распределяется по точкам. Если времени нет совсем, программа подставляет синтетические метки (отсчёт от 2000 года) и показывает предупреждение. Статистика по дням и фильтр по датам для таких данных не имеют смысла.
• Point — одиночная точка, трактуется как визит. Она учитывается в числе точек, но отдельным маркером на карте сейчас не рисуется: места показываются только для визитов длительностью от 5 минут, а у точки KML длительности нет.

5. Дополнительная информация

5.1. Что такое «аномалия»

Аномалия в этой программе означает, что координаты двух соседних по времени точек не сходятся друг с другом. Чтобы попасть из одной в другую за указанное время, потребовалась бы нереальная скорость.

Программа считает скорость по прямой между соседними точками: расстояние делится на разницу во времени. Если получилось больше порога (по умолчанию 300 км/ч, параметр MAX_PLAUSIBLE_SPEED_KMH в js/config.js), на второй точке пары ставится красный маркер. Подсказка выглядит так: Аномалия: 308 км/ч · 08.12.2025 14:32.

Число 308 означает расчётную скорость, а не то, что вы так ехали. Обычные причины:

• скачок GPS (плохой сигнал, здание, туннель);
• перемешанные записи из разных источников или перекрывающихся файлов;
• почти одинаковое время при разных координатах;
• настоящий перелёт: самолёт быстрее 300 км/ч, поэтому на полётах срабатывания нормальны.

Аномалии стоит считать подозрительными участками данных: они могут завышать статистику километров. Для анализа пеших и автомобильных поездок разумный порог 150–200 км/ч; если в данных есть перелёты, оставьте 300 и больше.

5.2. Тепловая карта мест посещений

Тепловая карта показывает, где вы проводили больше всего времени: чем дольше и чаще вы бывали в районе, тем «горячее» цвет (от голубого через янтарный к красному). Включается переключателем «Тепловая карта мест пребывания» в блоке «Слои карты» боковой панели; выбор запоминается.

Что рисуется. Только данные двух видов:

• VISIT — визиты, то есть места, где вы находились. Вес — длительность визита; визиты короче 5 минут не учитываются. Визит без длительности (например, Point из KML) получает фиксированный вес 5 минут.
• UNKNOWN — точки, для которых тип активности неизвестен: старый JSON, KML без распознанного названия, сегменты timelinePath без activity. Вес точки — время до следующей точки, не более 15 минут.

Точки с любой другой активностью (WALKING, IN_VEHICLE, CYCLING и т. д.) на тепловой карте не учитываются.

Остальные слои. Пока тепловая карта включена, все остальные слои скрыты: маршруты всех активностей, жёлтые круги мест (число посещений) и красные точки аномалий. Статистика и список мест слева продолжают работать.

Фильтры. Тепловая карта строится по текущим фильтрам (период и типы активности) и пересчитывается при их изменении. Если снять флажок «visit» или «UNKNOWN» в типах активности, соответствующие данные пропадут и с тепловой карты.

Выключение. Выключение переключателя работает как кнопка «Сбросить фильтры»: фильтры очищаются, а маршруты, места и аномалии рисуются заново.

Подсказка. При наведении курсора на переключатель показывается пояснение и число учтённых визитов и точек UNKNOWN; при загрузке нового файла или смене фильтров цифры обновляются.

Параметры (радиус, размытие, градиент, размер ячейки агрегации около 55 м, ограничения весов) задаются в разделе HEATMAP файла js/config.js. Библиотека Leaflet.heat лежит локально в vendor/leaflet-heat/, внешние серверы не нужны.

5.3. Одновременный просмотр нескольких файлов

Можно выбрать или перетащить сразу несколько файлов, в том числе разных форматов (например, Timeline.json и .kml). Программа объединит их в один общий таймлайн, отсортированный по времени. В статусе формат будет указан через плюс, например google_new+kml.

Важные особенности:

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

5.4. Карты для отображения: с API-ключом и без

Сейчас используется подложка CARTO (тёмная и светлая версии: dark_all и light_all). Подложка меняется вместе с темой страницы. Настройки находятся в js/config.js, раздел MAP.

CARTO с ключом (вариант по умолчанию). CARTO требует API-ключ для растровых тайлов. Без ключа карта всё равно загрузится, но поверх тайлов будет водяной знак «API KEY REQUIRED», и в консоли никакой ошибки не будет. Получите ключ на странице carto.com/basemaps/apikey и вставьте его в поле CARTO_API_KEY. После правки обновите страницу с очисткой кэша (Ctrl+Shift+R).

Без API-ключа. Подойдёт любой источник тайлов, не требующий ключа. Для этого нужно заменить адреса TILE_URL_DARK и TILE_URL_LIGHT в config.js, а поле CARTO_API_KEY оставить пустым. Например, стандартные тайлы OpenStreetMap:

TILE_URL_DARK:  'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
TILE_URL_LIGHT: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',

Учтите: у OpenStreetMap своя политика использования, она рассчитана на умеренную нагрузку, а не на интенсивную работу. Подложка у них светлая, поэтому в тёмной теме карта останется светлой. Кроме того, текст авторских прав (TILE_ATTRIBUTION) в config.js нужно привести в соответствие с выбранным источником.

Другие поставщики (MapTiler, Stadia Maps, Thunderforest и др.) обычно требуют собственный ключ, а имя параметра в адресе у каждого своё. Программа дописывает к адресу параметр ?key=... только для поля CARTO_API_KEY, поэтому для других поставщиков ключ проще вписать прямо в адрес тайлов.

Полностью автономный вариант. Если интернета нет или нужен контроль над данными, можно поднять собственный тайл-сервер (например, на основе MBTiles) и указать его адрес в TILE_URL_DARK и TILE_URL_LIGHT.

Как бы ни был настроен источник, сами данные Timeline в сеть не уходят.

5.5. Основные настройки (js/config.js)

Параметр	Значение по умолчанию	Что делает
APP_VERSION	4C.5	версия, которая показывается в шапке
MAP.CARTO_API_KEY	пусто	ключ CARTO для тайлов
ANALYSIS.MAX_PLAUSIBLE_SPEED_KMH	300	порог скорости для аномалий
ANALYSIS.MIN_VISIT_DURATION_MS	5 минут	минимальная длительность визита для списка мест
ANALYSIS.PLACE_CLUSTER_RADIUS_M	150 м	радиус объединения визитов в одно место
SIMPLIFIER.DEFAULT_TOLERANCE_M	15 м	допуск упрощения маршрутов
SIMPLIFIER.DETAIL_THRESHOLD_DAYS	14	при периоде не больше этого числа дней упрощение отключается
HEATMAP.POINT_VISIT_WEIGHT_MS	5 минут	вес визита без длительности (например, Point из KML)
HEATMAP.MAX_POINT_DWELL_MS	15 минут	максимальный вес одной точки UNKNOWN
HEATMAP.CELL_DEG	0.0005° (около 55 м)	размер ячейки, в которую сливаются точки тепловой карты
HEATMAP.RADIUS / HEATMAP.BLUR	22 / 18	радиус и размытие «тепла» на карте

Упрощение маршрутов. Чтобы карта не тормозила, линии упрощаются алгоритмом Дугласа-Пекера: лишние точки, почти лежащие на прямой, выбрасываются. Если в фильтрах заданы обе границы периода и он не длиннее 14 дней, упрощение отключается и линия рисуется по всем точкам. Если задана только одна граница, диапазон считается неограниченным и упрощение остаётся.

6. Если что-то не работает

• Видны только подписи, нет разметки и карты, не открывается выбор файла. Страница открыта через file://. Запустите локальный сервер (раздел 2).
• На карте водяной знак «API KEY REQUIRED». Вставьте ключ CARTO в config.js или смените источник тайлов (раздел 5.4).
• «Загружено: 0 точек». Откройте консоль браузера (F12): программа выводит диагностические сообщения с префиксами [TimelineViewer] и [TimelineMap]. Они показывают, сколько сегментов есть в файле, сколько осталось после фильтров и было ли применено упрощение.
• Красных точек слишком много. Это GPS-скачки или перемешанные записи; поднимите порог аномалий в config.js или сузьте период.
• KML: даты выглядят как 2000 год. В файле нет времени, программа подставила синтетические метки. Статистика по датам для такого файла недостоверна.

• В шапке старая версия, новые функции не работают. Браузер взял файлы из кэша: запустите python3 serve.py (раздел 2) и обновите страницу с очисткой кэша (Ctrl+Shift+R).
• Тепловая карта пустая. Откройте консоль (F12) и найдите строку тепловая карта: визитов=…, точек UNKNOWN=…. Если оба числа равны нулю, в выбранных данных нет ни визитов, ни точек UNKNOWN: все точки относятся к другим активностям, либо сняты флажки «visit» и «UNKNOWN» в фильтре. Нажмите «Сбросить фильтры» или выключите и снова включите переключатель.
• Тепловая карта включена, но маршрутов, жёлтых кругов и красных точек нет. Так и задумано: пока она включена, остальные слои скрыты. Выключите переключатель, чтобы вернуть их.