Карты

Поддерживаемые ресурсы

Для публичной интеграции используйте только поддерживаемые endpoints. Все запросы требуют API-ключ.

РесурсОписаниеПример
GET /api/styles/{theme}-ru-pmtiles.jsonJSON стиль карты: color, light, darkhttps://promaps.online/api/styles/color-ru-pmtiles.json?key=KEY
GET /api/vector-tiles/{z}/{x}/{y}Единый runtime endpoint для тайлов картыhttps://promaps.online/api/vector-tiles/10/619/319?key=KEY
GET /api/fonts/{fontstack}/{range}.pbfГлифы для подписей MapLibrehttps://promaps.online/api/fonts/Noto%20Sans%20Regular/0-255.pbf?key=KEY
GET /api/sprites[/theme]/sprite.{json|png}Иконки и sprite sheets для стиляhttps://promaps.online/api/sprites/sprite.json?key=KEY
GET /embedГотовая карта для iframe и WebViewhttps://promaps.online/embed?key=KEY&center=[37.6,55.7]&zoom=10&style=color
POST /api/routeПостроение маршрута, нужен routing keyhttps://promaps.online/api/route

Важно

Не нужно обращаться к внутренним архивным форматам или строить интеграцию вокруг raw файлов. Поддерживаемый путь для клиента: style JSON, vector tiles, fonts, sprites и при необходимости /embed.

Один запрос карты списывается при получении style JSON. Перемещение, масштабирование, тайлы, шрифты и спрайты этой открытой карты отдельно не расходуют лимит.

Своя карта через MapLibre

Этот вариант подходит, если вам нужны свои маркеры, popup, события, фильтры, кастомные слои и управление картой из кода.

  1. Установите maplibre-gl.
  2. Подготовьте style URL для нужной темы.
  3. Создайте карту через new maplibregl.Map(...).
  4. Через transformRequest добавляйте key ко всем запросам к promaps.online, если он ещё не добавлен.
  5. После load добавляйте свои markers, popup и слои поверх базовой карты.
import maplibregl from 'maplibre-gl';

const baseUrl = 'https://promaps.online';
const lightKey = import.meta.env.VITE_PROMAPS_API_KEY;
const darkKey = import.meta.env.VITE_PROMAPS_API_KEY_DARK;
const isDark = false;
const apiKey = isDark ? darkKey || lightKey : lightKey;
const styleName = isDark ? 'dark-ru-pmtiles' : 'color-ru-pmtiles';

const map = new maplibregl.Map({
  container: 'map',
  style: `${baseUrl}/api/styles/${styleName}.json?key=${encodeURIComponent(apiKey)}`,
  center: [37.6176, 55.7558],
  zoom: 10,
  transformRequest: (url) => {
    if (url.startsWith(baseUrl) && !url.includes('key=')) {
      const separator = url.includes('?') ? '&' : '?';
      return { url: `${url}${separator}key=${encodeURIComponent(apiKey)}` };
    }

    return { url };
  }
});

Разделение на light/dark ключи — это удобный пример для проектов с двумя темами. Если у вас одна тема, достаточно одного ключа и одного style URL.

Встраивание через iframe

Используйте /embed, если нужна готовая карта без своей логики поверх неё.

Этот режим уже включает обязательный логотип «ПроКарты» в правом нижнем углу. Убирать его нельзя.

<iframe
  src="https://promaps.online/embed?key=YOUR_API_KEY&center=[37.6176,55.7558]&zoom=10&style=color"
  width="100%"
  height="520"
  loading="lazy"
  style="border:0;border-radius:0;">
</iframe>
  • key обязателен.
  • center, zoom и style передаются через query.
  • Этот путь подходит для CMS, лендингов, корпоративных сайтов и быстрого MVP.

Построение маршрутов API: пример запроса

Для построения маршрутов используйте отдельный routing key. Учёт ведётся по новым участкам плана: А → Б — один участок; добавление В — ещё один. Перестроение по новой позиции автомобиля при тех же точках не расходует лимит.

fetch('https://promaps.online/api/route', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_ROUTING_KEY'
  },
  body: JSON.stringify({
    costing: 'driving',
    locations: [
      { lat: 42.9849, lon: 47.5047 },
      { lat: 42.9731, lon: 47.4910 }
    ],
    routeSession: {
      stopIds: ['delivery-1024']
    }
  })
}).then((response) => response.json());

Доступ к Построение маршрутов API

  • Routing API доступен в self-serve через отдельный routing key
  • Бесплатный лимит: 100 расчётных участков в месяц на ключ
  • Пакеты покупаются в личном кабинете и привязываются к выбранному routing key
  • Один маршрут может включать до 50 точек
  • В ответе на первый запрос с routeSession.stopIds приходит routeSession.id. Передавайте его и те же ID точек при перестроениях; новая точка добавляет один расчётный участок, удаление уже рассчитанной точки не возвращает расход.

Приложение и WebView

Как выбрать вариант

Если приложению нужен только готовый basemap, используйте /embed внутри WebView. Если нужны свои события, popup и плотная интеграция с UI, используйте тот же прямой путь через MapLibre, что и на сайте.

Android / iOS / Flutter / React Native

https://promaps.online/embed?key=YOUR_API_KEY&center=[37.6176,55.7558]&zoom=10&style=color

Для гибридных приложений

Если у вас React/Vite/Capacitor-сборка, после изменения web-кода обязательно пересоберите bundle и синхронизируйте assets в native shell.

npm run build
npx cap sync android