iFrame API · Справка Measure Map Online

Показывайте свой проект живой картой на собственном сайте — в единицах, стиле карты и теме, которые подходят вашему сайту.

iFrame API размещает карту проекта на вашей веб-странице. Посетители видят спутниковую карту с вашими измерениями и могут перемещаться по ней без аккаунта и не покидая ваш сайт. Вы выбираете проект, единицы измерения, стиль карты и цветовую тему.

Прежде чем начать#

Рабочий API-ключ с доступом Встроенные карты. См. API-ключи.
Проект, который могут видеть посетители. Установите для него уровень доступа Только для просмотра или Общедоступный. Проект с уровнем Частный не открывается для посетителей без аккаунта. См. какие проекты можно встраивать.
При желании — ограничения по сайтам для ключа, чтобы встроенная карта работала только на ваших сайтах. См. API-ключи.

Соберите код для встраивания#

Разработчик > Встроить карту собирает код за вас с вашим рабочим ключом: выберите проект, тему, единицы, тип карты и размер, проверьте результат в Живой предпросмотр и скопируйте Код для встраивания. Если проект частный, раздел сообщает об этом и предлагает Сделать «Только для просмотра». Каждый шаг описан в разделе получить код для встраивания.

Раздел «Встроить карту» с выбранным проектом и живым предпросмотром

Код содержит ваш ключ, поэтому он работает, пока вы не замените ключ. Раздел предупреждает, если ключ может больше, чем Встроенные карты, — ведь любой может прочитать его в исходном коде вашей страницы, — и если у ключа нет ограничений по сайтам. Кратковременный токен использует только Живой предпросмотр. См. ключ или токен.

Адрес встроенной карты#

Встроенная карта — это <iframe>, адрес которого начинается с https://app.measuremaponline.com/iframe_api, за которым следуют эти параметры:

Параметр	Нужен	Значения
`pid`	обязательно	Идентификатор проекта: часть адреса проекта в приложении после `/p/`.
`key`	`key` или `token`	Ваш API-ключ.
`token`	`key` или `token`	Токен от вашего сервера (см. ниже).
`ms`	необязательно	Единицы: `metric` или `imperial`. Без этого параметра посетители в США видят имперские единицы, а все остальные — метрические.
`maptype`	необязательно	`satellite` (по умолчанию), `map`, `hybrid` или `terrain`.
`theme`	необязательно	`auto` (по умолчанию: следует системной настройке посетителя), `light` или `dark`.

Минимальный пример#

<iframe src="https://app.measuremaponline.com/iframe_api?pid=YOUR_PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="YOUR_PROJECT_NAME" width="500" height="500" style="border:0" allow="fullscreen"></iframe>

Замените YOUR_PROJECT_ID, YOUR_API_KEY и YOUR_PROJECT_NAME (программы экранного доступа зачитывают title вслух) и задайте ширину и высоту под свою страницу.

Код для встраивания с кнопкой копирования

Ключ или токен#

С key, как в коде, который даёт раздел Встроить карту, встроенная карта работает, пока работает ключ, на тех сайтах, которые разрешают его ограничения. При этом ваш ключ виден в исходном коде страницы, поэтому:

используйте ключ только с доступом Встроенные карты;
ограничьте его своими сайтами;
заменив ключ, обновите страницы в течение 24 часов, пока старый ключ ещё работает.

С token ключ остаётся на вашем сервере. Это подходит для встроенных карт, которые ваш сервер вписывает в страницу при каждом посещении: перед показом страницы он запрашивает у REST API токен и подставляет его в адрес iframe:

POST https://api.measuremaponline.com/api/v2/auth/iframe/token с ключом в заголовке Authorization возвращает token, который действует 60 минут;
POST https://api.measuremaponline.com/api/v2/auth/token делает то же самое и принимает duration в секундах, до 24 часов. В ответе указано, когда истекает токен.

Ваш аккаунт может получать до 600 токенов в час. Используйте рабочий ключ: встроенные карты показывают только рабочие проекты, поэтому токен, созданный ключом песочницы, карту не откроет. См. справочник по API.

Что могут посетители#

Посетители могут перемещать и масштабировать карту и читать измерения ваших фигур. Изменить они ничего не могут: во встроенной карте редактирование отключено, каким бы ни был уровень доступа проекта. Единственное исключение — проект Open Guest на тарифе Open Guest, где посетители измеряют сами.

Если карта не появляется#

Проверьте по порядку:

В адресе token, срок действия которого истёк. Токены действуют 60 минут, если ваш сервер не запросил больший срок. Скопируйте код заново в разделе Встроить карту — он использует ваш ключ — или пусть ваш сервер получает новый токен для каждого посещения (см. выше).
Проект частный. Установите для него Только для просмотра или Общедоступный либо нажмите Сделать «Только для просмотра» в разделе Встроить карту.
Сайт не разрешён. Если у ключа есть ограничения по сайтам, страница со встроенной картой должна быть на одном из них. Некоторые браузеры и сайты скрывают, на какой странице находится встроенная карта; при заданных ограничениях такая карта отклоняется.
Ключ был заменён. Старый ключ перестаёт работать через 24 часа после создания нового или сразу, если его отозвали.
Это ключ песочницы. Встроенные карты работают только с рабочими ключами и рабочими проектами.
Подписка не активна или доступ к API приостановлен: об этом сообщается в разделе API-ключи.