API карты для разработчиков

Быстрый старт за 1 минуту

Вставьте код туда, где должна быть карта. Вместо dom-na-yamskoy — адрес вашего проекта: он есть в кабинете («Опубликовать» → «Код для сайта» → «JS API», там же готовый код). Карта рядом — ровно этот код.

<div id="kinjo-map" style="height:600px"></div>
<script src="https://map.kinjo.ru/widget.js"></script>
<script>
  const map = Kinjo.mount('#kinjo-map', { project: 'dom-na-yamskoy' });
  map.on('houseSelect', (house) => console.log(house?.name, house?.sales?.priceText));
</script>

Старый код с data-атрибутами работает и дальше. Тот же объект карты у него — Kinjo.mount(элемент).

<div data-kinjo data-project="dom-na-yamskoy" data-controls="-time,-header"></div>
<script src="https://map.kinjo.ru/widget.js" async></script>

Цены и квартиры у корпуса — передайте JSON

В карточке корпуса — «от 5,2 млн ₽», «10 квартир в продаже», примечание, свои строки и кнопка на выдачу квартир этого корпуса на вашем сайте (новая вкладка, utm_source=kinjo). Данные передаёт ваш сайт при встраивании: они остаются на странице и на наш сервер не уходят. Измените JSON и нажмите «Применить» — карточка на карте рядом обновится.

Kinjo.mount('#kinjo-map', {
  project: 'dom-na-yamskoy',
  houses: {
    "Корпус 1": {
      "priceFrom": 5200000,
      "flatsOnSale": 10,
      "url": "https://kinjo.ru/",
      "note": "Скидка 5% до 31.10",
      "button": "Выбрать квартиру",
      "lines": [
        {
          "label": "Сдача",
          "value": "IV кв. 2026"
        },
        {
          "label": "Отделка",
          "value": "White box"
        }
      ]
    },
    "Корпус 2": {
      "priceFrom": 7850000,
      "flatsOnSale": 4
    }
  },
});

Ключ — ID дома из кабинета (k1) или название ('Корпус 1'). Всё необязательно; что не передано — не показываем. Данные со страницы главнее заполненного в кабинете, null убирает поле кабинета. Всё выводится текстом, не HTML; неподходящее (http-ссылка, лишнее поле) пропускается с предупреждением в консоли.

Без своего JavaScript

JSON — прямо внутри блока карты, например, из шаблона CMS:

<div data-kinjo data-project="dom-na-yamskoy">
  <script type="application/json" data-kinjo-houses>
    { "Корпус 1": { "priceFrom": 5200000, "flatsOnSale": 10, "url": "https://ваш-сайт.ru/flats?k=1" } }
  </script>
</div>
<script src="https://map.kinjo.ru/widget.js" async></script>

На лету

// сайт сам взял цены из своей CRM — передаёт карте на лету
const prices = await fetch('/api/my-prices').then((r) => r.json());
await map.setHouses({
  k1: { priceFrom: prices.k1.min, flatsOnSale: prices.k1.count },
  k2: { priceFrom: prices.k2.min, flatsOnSale: prices.k2.count },
});

Свой iframe — Kinjo.connect(iframe).setHouses({...}). В событии houseSelect приходит итог: house.sales.priceText, flatsText, note, lines.

Страница квартиры

Рядом с планировкой — дом квартиры в ЖК: только сам ЖК с подсвеченным домом, без мест, категорий, солнца, шапки и карточек. Камера сама встаёт так, чтобы дом был в центре и целиком и его не заслоняли соседи. Карту можно вращать и приближать: на компьютере — мышью (колесо — с Ctrl или ⌘), на телефоне — двумя пальцами. Грузится быстро: места, маршруты и зоны в этом режиме не загружаются; на слабом телефоне — 2D с подсветкой.

Кнопка «Открыть карту» в углу открывает полную карту поверх страницы: все элементы, тот же дом выбран, его карточка открыта (с ценами из houses, если вы их передали). Закрыть — ✕, Esc, «назад» или свайп вниз; фокус вернётся на кнопку. Попробуйте:

<div id="flat-map" style="height:420px"></div>
<script src="https://map.kinjo.ru/widget.js"></script>
<script>
  Kinjo.mount('#flat-map', {
    project: 'dom-na-yamskoy',
    house: 'Корпус 2',   // дом квартиры: ID, название или подпись
    view: 'house',
  });
</script>

<div data-kinjo data-project="dom-na-yamskoy" data-house="Корпус 2" data-view="house"
     data-open-label="Дом на карте" style="height:420px"></div>
<script src="https://map.kinjo.ru/widget.js" async></script>

Дом — как в selectHouse: ID из кабинета, ID части, название или подпись. section (data-section) подсветит секцию или подъезд, если дом в модели из частей. openLabel (data-open-label) — своя подпись кнопки, false ("0") — без неё. Высота — у блока, без неё — 420 px. Цены и квартиры (houses, data-kinjo-houses) передаются и в полную карту. События mapOpen и mapClose — когда карту открыли и закрыли.

<iframe src="https://map.kinjo.ru/?project=dom-na-yamskoy&house=%D0%9A%D0%BE%D1%80%D0%BF%D1%83%D1%81%202&view=house&embed=1"
        style="width:100%;height:420px;border:0" title="Дом на карте ЖК"></iframe>

Без widget.js кнопка открывает полную карту в новой вкладке (данные houses туда не попадут — их передаёт widget.js). Ключи API не нужны.

Параметры

Kinjo.mount(el, options) — el элемент или селектор. Возвращает объект карты: методы-обещания и события.

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

Спрячьте наши кнопки, если ставите свои. Переключайте — карта рядом меняется, а ниже — код, который получится.

Kinjo.mount('#kinjo-map', {
  project: 'dom-na-yamskoy',
});

Без JavaScript — атрибут data-controls="none" или "-time,-header"; у iframe — &ui=none.

Вид под стиль сайта

Форма и размер пинов мест, скругление элементов карты — дока, кнопок, карточек, плашек, панелей и листа на телефоне — и размер дока. Обычно это настраивают в кабинете: «Настройки проекта» → «Карта на сайте» → «Вид элементов». Параметры встраивания переопределяют проект для одного сайта.

Kinjo.mount('#kinjo-map', {
  project: 'dom-na-yamskoy',
  pinShape: 'badge',  // значок без точки ('pin' — с точкой, 'dot' — метка)
  pinRadius: 0,       // квадратные пины (50 — круглые)
  pinSize: 'm',       // 's', 'm', 'l'
  uiRadius: 0,        // прямые углы у кнопок, карточек и панелей (24 — капсулы)
  dockSize: 's',      // док поменьше: 'm' — стандартный, 'xs' — очень маленький
});

<div data-kinjo data-project="dom-na-yamskoy" data-pin-shape="badge" data-pin-radius="0" data-ui-radius="0"></div>

У iframe — &pinShape=badge&pinRadius=0&pinSize=m&uiRadius=0&dockSize=s. Цвета пинов — по категориям из проекта. Смена параметров через Kinjo.update(el, {'{'} uiRadius: 12 {'}'}) перезагружает карту.

Методы

Все методы возвращают Promise. Команды, отправленные до загрузки карты, ждут её. Ошибка — Error с полем code: unknown_house, bad_args, unavailable, route_failed, origin_not_allowed, timeout.

const house = await map.selectHouse('Корпус 1');
console.log(house.sales?.priceText); // «от 5,2 млн ₽»

await map.setHouses({ 'Корпус 2': { priceFrom: 7850000, flatsOnSale: 4 } });
await map.updateHouse('Корпус 2', { note: 'Последние 4 квартиры' });
await map.updateHouse('Корпус 2', null);

await map.setTime('22:30');      // ночь: окна светятся
await map.setDate('2026-12-21');  // зима
await map.setTime(new Date());    // сейчас

await map.setMode('2d');
await map.setTheme('dark');

const r = await map.routeTo({ address: 'Тюмень, ул. Республики, 1' });
console.log(r.minutes, r.km, r.mode); // 23 1.7 'walk'

await map.routeTo({ lngLat: [65.534, 57.153], label: 'Офис продаж' }, { mode: 'drive' });
await map.clearRoute();

await map.showCategories(['edu', 'health']);
await map.showAllPlaces();

await map.setWalkZone(15);
await map.setWalkZone(null);
await map.openCity();

await map.flyTo({ center: [65.5059, 57.1645], zoom: 18, bearing: 60, pitch: 62 });
await map.resetView();

await map.setControls('none');            // только карта
await map.setControls({ time: true });     // вернуть время
await map.setControls('all');

Ещё: getState() — режим, выбранный дом, время; destroy() — убрать карту.

События

Подписка — map.on(name, fn), map.off, map.once. Те же события приходят на блок карты как kinjo:<name>. Нажмите что-нибудь на карте — события появятся здесь.

1. Пока тихо: выберите корпус на карте или нажмите «Выполнить» у метода.

map.on('ready', (info) => console.log(info.houses));
map.on('houseSelect', (house) => {
  if (!house) return;                         // выбор сняли
  showMyCard(house.name, house.sales?.priceText, house.url);
});
map.on('routeBuilt', (r) => console.log(r.to, r.minutes, r.mode));
map.on('flatsClick', (h) => ym(XXXXXX, 'reachGoal', 'kinjo_flats'));

Свой iframe

Если на сайте уже стоит iframe с картой, подключитесь к нему — тот же объект карты. Наши кнопки у iframe задаёт параметр ui: none — только карта, -time,-header — без перечисленных.

<iframe id="kinjo-map" src="https://map.kinjo.ru/?project=dom-na-yamskoy&embed=1&ui=none"
        style="width:100%;height:600px;border:0" allow="fullscreen"></iframe>
<script src="https://map.kinjo.ru/widget.js"></script>
<script>
  const map = Kinjo.connect('#kinjo-map');
  map.ready.then(() => map.selectHouse('Корпус 1'));
</script>

Ограничение по сайтам

Кабинет → «Настройки проекта» → «Сайт и API» → «Сайты, где можно управлять картой». Если список задан, команды с других сайтов отклоняются (origin_not_allowed) и события туда не идут. Пусто — с любого. https://www.site.ru и https://site.ru — разные сайты.

Через API доступны только действия с картой: никаких данных кабинета, черновиков и ключей. Карта принимает команды только от страницы, в которую встроена, и отвечает только ей.

Типы TypeScript

Методы, параметры и события описаны в kinjo.d.ts: положите файл в проект — window.Kinjo станет типизированным.

// скачайте https://map.kinjo.ru/kinjo.d.ts в проект (например, types/kinjo.d.ts)
import type { KinjoMap, KinjoHouse } from './types/kinjo';

const map: KinjoMap = Kinjo.mount('#kinjo-map', { project: 'dom-na-yamskoy' });
map.on('houseSelect', (house: KinjoHouse | null) => { /* … */ });

useEffect(() => {
  const map = window.Kinjo.mount(ref.current, { project: 'dom-na-yamskoy' });
  map.on('houseSelect', setHouse);
  return () => map.destroy();
}, []);