Документация виджета карты maps.gumy.space

Карта встраивается на сайт через iframe. Управление через URL-параметры. Главный URL: https://maps.gumy.space/

1. Быстрый старт

Простейший iframe:

<iframe src="https://maps.gumy.space/" width="100%" height="600" style="border:0"></iframe>

В виджет-режиме без UI:

<iframe src="https://maps.gumy.space/?chrome=none" width="100%" height="500" style="border:0"></iframe>

2. Параметры внешнего вида

2.1 Тонкое управление UI (для встраивания)

Каждый параметр on|off (синонимы: 1|0, true|false, yes|no). Дефолт берётся из пресета chrome=; параметр явно переопределяет пресет. Это позволяет смешивать: например chrome=none&search=on — чистая карта плюс поиск.

2.2 Примеры комбинаций

Только карта без всего UI (виджет на главной партнёра):

https://maps.gumy.space/?chrome=none

Чистая карта без точек — только маршрут доставки, без шума:

https://maps.gumy.space/?mode=delivery&car_id=12345&delivery_to=Moscow&chrome=none&pins=off

Карта-картинка для preview-блока (без зума, без интерактивности, без точек):

https://maps.gumy.space/?chrome=none&pins=on&interactive=off&zoom=off

Минимум UI плюс поиск (чистая карта + строка поиска):

https://maps.gumy.space/?chrome=none&search=on

Каталог-режим — карта + список авто справа, без строки поиска:

https://maps.gumy.space/?chrome=catalog

Список слева, всё остальное как в каталоге:

https://maps.gumy.space/?chrome=catalog&list_side=left

Каталог + сортировка по самой низкой цене:

https://maps.gumy.space/?chrome=catalog&sort=total_price_rub&order=ASC

Тёмная тема, английский, без UI:

https://maps.gumy.space/?theme=dark&lang=en&chrome=none

Подгон под фирменный цвет host-сайта (оранжевый акцент):

https://maps.gumy.space/?chrome=catalog&accent=ff5722

Разные акценты для light и dark (например, для сайта со своей тёмной темой):

https://maps.gumy.space/?accent=2563eb&accent_dark=60a5fa

Brand-страница на стороннем сайте (только Toyota, минимальный chrome):

https://maps.gumy.space/?brand=Toyota&chrome=minimal

3. Фильтры машин

Все фильтры передаются как URL-параметры.

3.1 Базовые фильтры

3.2 Расширенные фильтры

Все эти параметры — те же, что возвращает /v1/search/parse на api.proride.io, и пишутся в URL виджета без изменений. Совпадают с каноном ai-auto.tech.

Зарезервировано / not yet implemented: max_delivery_days — параметр принимается ради forward-compat, но колонки в БД пока нет, реальная фильтрация отключена.

Пример (базовые + расширенные):

https://maps.gumy.space/?brand=Toyota&model=Camry&transmission=Автомат&max_year=2026&min_price=5000000&max_price=10000000&countries=georgia,uzbekistan&steering_side=left,right&condition=used&has_accident=false&owner_count=1&min_engine_l=2.0&max_engine_l=3.5&min_power=150&profitability=profitable

4. Список авто (рейл / bottom-sheet)

Помимо точек на карте есть боковая панель со списком авто. На desktop — узкий рейл (340px) слева или справа, на мобиле — bottom-sheet, прибитый к нижней границе экрана и раскрываемый тапом по шапке.

Список тянется из /api/cars-list по тем же фильтрам, что и точки, плюс bbox видимой области карты. При перетаскивании карты список перезагружается автоматически (debounce 220 мс). Подгрузка следующих страниц — через IntersectionObserver на сентинеле в конце.

4.1 Управление списком

Селектор сортировки в шапке списка использует короткие пресеты-токены (popular, profit, price_desc, price_asc, year_desc, mileage_asc), но в URL пишется всегда канонический вид sort=…&order=… — чтобы ссылка из адресной строки работала идентично на всех сайтах экосистемы.

Общий счётчик авто живёт в верхнем поиск-баре («99 733 авто») — дублировать его в шапке списка не имеет смысла, так что в list-head теперь только сортировка и кнопка «Все в области». Тап по точке на карте «пинит» панель к этой точке (показывает только авто из этой координаты); кнопка «Все в области» в шапке возвращает к bbox-режиму.

4.2 Цена

API всегда возвращает две цены в рублях:

• price_rub — цена источника в стране продавца, конвертированная бэкендом из локальной валюты по курсу.
• total_price_rub — итоговая цена с доставкой в РФ (растаможка + логистика по дефолтному маршруту).

Что показывать на карточке — задаётся URL-параметрами:

Если по выбранному режиму цены нет (или это известная заглушка 1 000 000 ₽), фронт фолбечится на второе поле. Если ни одно не валидно — выводится прочерк «—».

Примеры:

https://maps.gumy.space/?currency=usd                              # цены в долларах, итоговые
https://maps.gumy.space/?price_kind=source                         # без доставки, ₽
https://maps.gumy.space/?price_kind=source&currency=usd            # без доставки, $
https://maps.gumy.space/?price_kind=source&currency=source         # цена источника в его валюте (₩, $, €, …)

4.3 Примеры

Каталог-страница на отдельном домене (только список + карта, без поиска):

https://maps.gumy.space/?chrome=catalog

Каталог с фильтром (Toyota Camry, лучшее по рейтингу):

https://maps.gumy.space/?chrome=catalog&brand=Toyota&model=Camry

Boxеd-режим: список слева, поиск сверху, цена по возрастанию:

https://maps.gumy.space/?list=on&list_side=left&sort=total_price_rub&order=ASC

5. Поиск по радиусу

Можно ограничить выдачу кругом вокруг произвольной точки. Фильтр работает на бэке: применяется к точкам на карте (/api/cars-geo), к списку (/api/cars-list), к счётчикам и к попапу машин в точке (/api/cars-at) — всё одной парой параметров.

Оба параметра обязательны вместе. Если задан только один — фильтр молча игнорируется (та же логика, что и у остальных URL-параметров: кривой ввод не должен ломать страницу).

5.1 Примеры

Машины в радиусе 100 км вокруг Тбилиси:

https://maps.gumy.space/?near=41.7151,44.8271&radius_km=100

Toyota Camry в радиусе 500 км вокруг Москвы (комбинируется с любыми другими фильтрами):

https://maps.gumy.space/?brand=Toyota&model=Camry&near=55.7558,37.6173&radius_km=500

Каталог-режим, авто в 250 км от заданной точки, по возрастанию цены:

https://maps.gumy.space/?chrome=catalog&near=55.7558,37.6173&radius_km=250&sort=total_price_rub&order=ASC

Виджет «рядом с городом» (минимальный chrome, авто-подгон viewport):

https://maps.gumy.space/?chrome=minimal&near=43.2220,76.8512&radius_km=150

5.2 Как считается

На бэке сначала отрезается прямоугольный bbox (быстро, по индексу lat/lng), затем точная отсечка по формуле гаверсинуса (R = 6371 км). На антимеридиане работает корректно — bbox разворачивается в две половины. На очень больших радиусах (когда круг покрывает все долготы) lng-pre-filter отключается, отсечку делает только haversine.

Маршрутизация по дорогам не учитывается — это геодезическое расстояние по большому кругу. Тот же подход, что у delivery-режима.

6. Режим доставки

Активируется параметром mode=delivery. Карта рисует пунктирную линию от города машины до города доставки и показывает банер сверху.

Пример:

https://maps.gumy.space/?mode=delivery&car_id=12345&delivery_to=Moscow

В виджет-режиме (без UI):

https://maps.gumy.space/?mode=delivery&car_id=12345&delivery_to=Москва&chrome=none&theme=light

7. Полный пример

https://maps.gumy.space/
  ?brand=Toyota
  &model=Camry
  &transmission=Автомат
  &body_type=Внедорожник
  &max_year=2026
  &min_price=5000000
  &max_price=10000000
  &countries=georgia,uzbekistan
  &max_mileage=160000
  &steering_side=left,right
  &condition=used
  &has_accident=false
  &owner_count=1
  &min_engine_l=2.0
  &max_engine_l=3.5
  &min_power=150
  &profitability=profitable
  &near=41.7151,44.8271
  &radius_km=300
  &sort=total_price_rub
  &order=ASC
  &theme=dark
  &lang=en
  &chrome=minimal
  &clusters=off
  &pins=on
  &search=on
  &filters=on
  &count=on
  &zoom=on
  &attribution=on
  &interactive=on
  &auto_fit=on

8. API эндпоинты

Карта использует эти HTTP-эндпоинты. Их можно вызывать напрямую.

9. Замечания

• URL-параметры читаются один раз при загрузке iframe. Чтобы изменить состояние из родительского сайта — пересоздайте src.
• Внутри виджета фильтры пишутся обратно в URL через history.replaceState. Параметры theme/lang/chrome/clusters/mode/delivery_*/car_id не трогаются — ими управляет родительский сайт.
• Маршрут доставки — это геодезическая прямая (большой круг), а не дорога.
• При chrome=none скрываются также стандартные элементы управления MapLibre (зум) и счётчик/поиск/фильтры; attribution остаётся включённым.
• Тонкие параметры (pins, search, filters, count, zoom, attribution, interactive, auto_fit) переопределяют пресет chrome= — можно смешивать в любых комбинациях.
• Кнопка темы внутри модалки фильтров записывает выбор в localStorage; URL theme= побеждает только при первой загрузке.
• Скрытие attribution=off допускается только если копирайт OSM показан где-то на host-странице (требование лицензии тайлов).
• Цены: по умолчанию итоговые с доставкой, в ₽; параметрами price_kind и currency переключаются на «без доставки» и USD соответственно. Подробнее — раздел 4.2.