Интерактивная карта работает только там, где работает JavaScript. В письме клиенту, в PDF-счёте, в карточке для мессенджера, в распечатанной схеме проезда и на странице, которую открыл поисковый робот, нужна обычная картинка. Kartrout отдаёт карту в виде PNG одним запросом: вы указываете центр, масштаб, размер и при желании метки и линию маршрута. В статье — как это устроено, какой ключ использовать в разных ситуациях (здесь легко ошибиться), сколько это стоит и какие у метода границы.
Когда нужна картинка, а не интерактивная карта
- Письма. Подтверждение заказа с адресом пункта выдачи, напоминание о визите, приглашение на встречу: получатель видит, куда ехать, не открывая сайт.
- PDF и печать. Договоры, акты выезда, схемы проезда к офису, маршрутные листы курьеров.
- Превью ссылок. Карточка для мессенджера или соцсети (картинка
og:image) со схемой места. - Страницы без скриптов. Запасной вариант, пока загружается виджет, и версия для роботов и читалок.
- Отчёты. Снимок зоны или маршрута, который нужно приложить к документу как есть.
Если посетителю нужно двигать и приближать карту, берите виджет (как вставить карту на сайт). Картинка дешевле по квоте: один рендер — одна единица, а сама карта потом открывается сколько угодно раз.
Запрос: минимальный набор параметров
GET https://kartrout.ru/v1/staticmap?lon=37.6173&lat=55.7558&zoom=14&width=760&height=440&key=pk_live_ВАШ_КЛЮЧОтвет — готовый PNG (Content-Type: image/png), внизу справа на нём уже напечатано «© OpenStreetMap contributors»: отдельно подписывать источник не нужно, но и убирать эту надпись нельзя.
| Параметр | Что делает | Ограничения |
|---|---|---|
lon, lat | Центр картинки | Точка должна лежать в зоне покрытия (Россия) |
zoom | Масштаб | от 0 до 18, дробные значения допустимы (например, 14.5) |
width, height | Размер в пикселях | от 1 до 1280 по каждой стороне |
scale | 2 — картинка для экранов высокой плотности: тот же охват, вдвое больше пикселей | 1 (по умолчанию) или 2 |
style | Оформление карты | light (по умолчанию), warm, dark |
marker | Метка в точке lon,lat; параметр можно повторять | до 10 меток |
path | Линия через точки lon,lat|lon,lat|…; можно повторять | до 3 линий, до 100 точек в каждой |
strokeColor, strokeWidth | Цвет (шесть шестнадцатеричных цифр, например 4F46E5) и толщина линий | толщина от 1 до 10; цвет и толщина общие для всех линий запроса |
Обратите внимание на разделитель в path: точки соединяются вертикальной чертой |, а не точкой с запятой. Точка с запятой внутри значения параметра теряется при стандартном разборе адреса, и линия просто не нарисуется. Если вы собираете адрес запроса кодом, пропускайте значения через штатную функцию кодирования параметров (urlencode в Python, URLSearchParams в JavaScript).
Метки и маршрут на карте
Типичная картинка для письма: маршрут от станции метро до пункта выдачи с отметкой по пути. Линию можно взять из ответа нашего же метода маршрута (/v1/route/driving/…?overview=full&geometries=geojson), оставив каждую пятую-шестую точку, чтобы не упереться в лимит в 100 точек.
GET https://kartrout.ru/v1/staticmap
?lon=37.6088&lat=55.7619&zoom=13.7&width=760&height=440&scale=2&style=light
&marker=37.5963,55.7699
&marker=37.6213,55.7539
&path=37.5963,55.7699|37.6038,55.7655|37.6120,55.7601|37.6213,55.7539
&strokeColor=4F46E5&strokeWidth=5
&key=pk_live_ВАШ_КЛЮЧ
scale=2: три метки и линия маршрута от Маяковской к Красной площади (5,1 км по дорогам). Картинка 1520 × 880 пикселей показана в половину размера, поэтому текст на ней чёткий и на экранах высокой плотности.Метка у нас одна — стандартная булавка: свою иконку или цвет задать нельзя. Если нужны подписи («Склад», «Точка выдачи №3»), добавьте их текстом в письме рядом с картинкой или нарисуйте поверх на своей стороне.
Три стиля и значки заведений
Для статичных карт доступны три оформления: светлое, тёплое и тёмное. Остальные темы виджета (белая, серая, чёрная и ваши собственные цвета) для картинок не подключены. Выбирайте по тому, где картинка будет лежать: тёмный стиль хорошо смотрится в тёмной теме письма и в мобильных приложениях, светлый — в печати.
light, warm и dark.На крупных масштабах на карте рисуются значки магазинов, аптек, кафе, банков, заправок, гостиниц, школ и других заведений с названиями. Для схемы проезда это удобно: получатель видит знакомые ориентиры — банк на углу, аптеку напротив. Чтобы значки были хорошо различимы, берите zoom от 16 и scale=2.
Какой ключ использовать: сайт, письмо, сервер
Здесь чаще всего возникает путаница, потому что картинка запрашивается обычным адресом, как любая другая. Правила такие.
| Где картинка | Что использовать |
|---|---|
На вашем сайте, в теге <img> | Публичный ключ pk_live_… с вашим доменом в списке разрешённых. Браузер сам сообщает адрес страницы, по нему ключ и проверяется. |
| В письме, PDF, мессенджере | Не ссылка на наш API. Запросите PNG на своём сервере секретным ключом, сохраните файл и вложите его в письмо (или положите на свой хостинг и ссылайтесь на него). |
| В серверном коде, скриптах, отчётах | Секретный ключ sk_live_… в заголовке Authorization: Bearer. |
Почему нельзя вставить ссылку на API прямо в письмоПочтовые программы и их серверы-посредники загружают картинки сами и не передают адрес вашего сайта. Публичный ключ с привязкой к домену в этом случае получает ответ 403 «origin not allowed for this key» (мы проверили такой запрос без заголовков Origin и Referer). А секретный ключ в адресе картинки мы отклоняем с ошибкой 401: он попал бы в журналы, прокси и историю браузера всех получателей.
Запрос с сервера выглядит так:
curl -H "Authorization: Bearer sk_live_ВАШ_СЕКРЕТНЫЙ_КЛЮЧ" \
"https://kartrout.ru/v1/staticmap?lon=37.6173&lat=55.7558&zoom=15&width=600&height=360&scale=2&marker=37.6173,55.7558" \
-o karta.pngТо же на Python с адресом, собранным из словаря параметров:
import requests
params = [
("lon", 37.6173), ("lat", 55.7558), ("zoom", 15),
("width", 600), ("height", 360), ("scale", 2),
("marker", "37.6173,55.7558"),
]
r = requests.get("https://kartrout.ru/v1/staticmap", params=params,
headers={"Authorization": "Bearer sk_live_ВАШ_СЕКРЕТНЫЙ_КЛЮЧ"}, timeout=30)
r.raise_for_status()
open("karta.png", "wb").write(r.content) # дальше — вложение в письмо или PDFКвота, кеш и скорость
- Один рендер — одна единица квоты «Статичные карты», независимо от размера картинки и числа меток. Лимиты за 30 дней: 20 на «Базовом», 150 на «Старте», 500 на «Бизнесе», 2 000 на «Масштабе».
- Повтор бесплатный. Готовые картинки хранятся на сервере и отдаются по тем же параметрам без нового рендера и без списания. Поэтому одна и та же карта пункта выдачи, открытая в тысяче писем, стоит одну единицу. Совпадать должны все параметры, включая координаты метки: сдвиг метки на метр — это уже другая картинка.
- Ошибки не списываются. Если запрос отклонён (400) или сервер не справился (5xx), единица возвращается.
- Скорость. По нашим замерам 14 октября 2026 года новая картинка 600 × 400 появилась за 1,4 секунды, повтор из хранилища — за 0,5 секунды вместе с сетевой задержкой.
Рендер идёт по одномуСервер рисует картинки по одной, чтобы не перегружать общий сервер. Если в момент вашего запроса уже идёт чужой рендер, вы получите ответ 503 с заголовком Retry-After: 3. Для страницы с несколькими картинками это значит: не запрашивайте их все новыми параметрами одновременно. Для пакетной подготовки (например, карты для всех пунктов выдачи) делайте запросы по очереди и повторяйте при 503 через указанное число секунд.
Типичные ошибки
| Ответ | Причина | Что делать |
|---|---|---|
| 400 «point is outside the area this deployment covers» | Центр, метка или точка линии вне зоны покрытия | Проверьте порядок координат: сначала долгота, потом широта |
| 400 «width must be 1-1280» и подобные | Параметр вне допустимых границ | Сверьтесь с таблицей выше |
| 401 «secret keys must be sent as Authorization: Bearer…» | Секретный ключ передан в адресе | Переместите его в заголовок |
| 403 «origin not allowed for this key» | Публичный ключ, домен страницы не в списке либо запрос пришёл без заголовков Origin/Referer (письмо, скрипт) | Добавьте домен в ключ или запрашивайте картинку с сервера секретным ключом |
| 503 «a map is already being rendered…» | Сервер занят другим рендером | Повторите через 3 секунды |
Чего статичная карта не умеет
- Нет собственных иконок меток и цветов отдельных меток: только стандартная булавка.
- У всех линий запроса общие цвет и толщина; многоцветный маршрут из нескольких отрезков одним запросом не нарисовать.
- Нет подписей поверх карты и многоугольников (зон доступности): для зоны можно передать её контур как линию с замыканием, но без заливки.
- Только три стиля и только территория покрытия сервиса.
- Картинка не обновляется сама: если пункт переехал, в запросе должны быть новые координаты.
Практический порядок работы
- Определите, где картинка будет жить: на сайте (публичный ключ) или в письме и документе (серверный запрос).
- Выберите размер с запасом по пикселям:
scale=2для экранов и печати. - Для сайта добавьте домен в ключ (как это сделать), для писем создайте секретный ключ и храните его только на сервере.
- Один раз сгенерируйте картинки для всех постоянных мест (пункты выдачи, офисы) и сохраните их у себя: так вы не зависите от квоты и скорости при каждой рассылке.
- Следите за остатком в разделе «Использование» личного кабинета.
Частые вопросы
Можно ли вставить картинку карты прямо в письмо?
Не ссылкой на API. Почтовые клиенты и их прокси загружают картинки сами и не передают адрес вашего сайта, поэтому публичный ключ с привязкой к домену получает ответ 403. Запросите PNG на своём сервере секретным ключом в заголовке Authorization: Bearer и вложите готовый файл или положите его на свой хостинг.
Какой максимальный размер картинки?
До 1280 пикселей по каждой стороне. С параметром scale=2 число пикселей удваивается (картинка 760 × 440 даёт файл 1520 × 880), а охват карты остаётся прежним.
Сколько меток и линий можно нарисовать?
До 10 меток (параметр marker=lon,lat повторяется) и до 3 линий по 100 точек (параметр path, точки разделяются символом |). Метка одна — стандартная булавка, у всех линий общие цвет и толщина.
Сколько стоит одна картинка в квоте?
Один рендер — одна единица квоты «Статичные карты»: 20 за 30 дней на «Базовом», 150 на «Старте», 500 на «Бизнесе», 2 000 на «Масштабе». Повторный запрос с теми же параметрами отдаётся из хранилища и не списывается; ошибочные запросы (400 и 5xx) тоже возвращают единицу.
Какие стили доступны для статичной карты?
Три: light (по умолчанию), warm и dark. Остальные темы виджета и собственные цвета для картинок не подключены.
Что значит ответ 503 «a map is already being rendered»?
Сервер рисует картинки по одной, и в момент вашего запроса занят чужой рендер. Повторите запрос через число секунд из заголовка Retry-After (3). Единица квоты при этом не списывается. При пакетной подготовке картинок делайте запросы по очереди.
