MediaLAN Routing API

1. О сервисе

MediaLAN Routing API — это HTTP-сервис маршрутизации и геокодинга, построенный на собственном развёртывании с данными OpenStreetMap. Сервис принимает координаты или адреса, возвращает оптимальные маршруты, расстояния, время в пути и адресные описания — всё, что нужно приложению доставки, такси или логистической платформе.

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

Кому подойдёт

Возможности

• Построение маршрутов между двумя точками — расстояние (метры), время (секунды) и полная геометрия (GeoJSON LineString или polyline) с ограничивающим прямоугольником (bbox) для автозума;
• Прямой геокодинг — поиск координат по текстовому адресу с короткими человекочитаемыми метками («ул. Чичерина, 37Б, Челябинск»);
• Обратный геокодинг — адрес по координатам с полной адресной структурой;
• Контроль квот — остаток суточного лимита в каждом ответе и в заголовках X-RateLimit-*;
• Статус ключа — метод status для мониторинга расхода запросов из вашего приложения.

Покрытие и профили

2. Тарифы и лимиты

Лимиты считаются в запросах за календарные сутки (сброс в 00:00 по московскому времени).

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

1. Зарегистрируйтесь в личном кабинете (email и пароль).
2. В разделе «Демо-ключ» нажмите «Сгенерировать демо-ключ» — ключ действует бессрочно и даёт 50 запросов в сутки.
3. Выполните первый запрос:

curl -G "https://api.medialan74.ru/api/v1/route" \
     -H "X-API-Key: <ВАШ_КЛЮЧ>" \
     --data-urlencode "from=61.4030,55.1644" \
     --data-urlencode "to=61.3750,55.1900"

Ответ:

{
  "status": "ok",
  "data": {
    "distance": 5530.7,
    "duration": 604.4,
    "profile": "driving",
    "geometry": {
      "type": "LineString",
      "coordinates": [[61.40301, 55.16438], [61.40289, 55.16512], "..."]
    },
    "bbox": [[61.37, 55.16], [61.40, 55.19]]
  },
  "quota": {
    "limit": 50,
    "used": 1,
    "remaining": 49,
    "reset": "2026-10-17T00:00:00+03:00"
  }
}

Где distance — метры, duration — секунды, geometry — массив точек [долгота, широта] в порядке GeoJSON.

4. Авторизация

Типы ключей

Ключ можно передать одним из трёх способов (приоритет — сверху вниз):

1. Заголовок X-API-Key: <ключ> — рекомендуется;
2. Заголовок Authorization: Bearer <ключ>;
3. GET-параметр ?api_key=<ключ> — удобно для отладки из браузера.

Квоты и заголовки

Счётчик суточных запросов сбрасывается в полночь (00:00, Europe/Moscow). В каждом ответе присутствует блок:

"quota": {
  "limit": 50,        // всего запросов в сутки
  "used": 12,         // израсходовано сегодня
  "remaining": 38,    // осталось
  "reset": "2026-10-17T00:00:00+03:00"   // когда сбросится
}

Та же информация дублируется в HTTP-заголовках:

• X-RateLimit-Limit — суточный лимит;
• X-RateLimit-Remaining — остаток;
• X-RateLimit-Reset — время сброса (ISO 8601).

При исчерпании квоты API возвращает 429 — запрос не будет выполнен до следующих суток.

5. Методы API

Базовый URL: https://api.medialan74.ru/api/v1 · Все методы — GET · Формат ответа — JSON (UTF-8).

curl -G "https://api.medialan74.ru/api/v1/route" \
     -H "X-API-Key: <ключ>" \
     --data-urlencode "from=61.4030,55.1644" \
     --data-urlencode "to=61.3750,55.1900" \
     --data-urlencode "profile=driving"

{
  "status": "ok",
  "data": {
    "distance": 5530.7,          // метры
    "duration": 604.4,           // секунды
    "profile": "driving",
    "geometry": {
      "type": "LineString",
      "coordinates": [[61.40301, 55.16438], [61.40289, 55.16512]]
    },
    "bbox": [[61.37, 55.16], [61.40, 55.19]]
  },
  "quota": { "limit": 50, "used": 3, "remaining": 47, "reset": "..." }
}

curl -G "https://api.medialan74.ru/api/v1/geocode" \
     -H "X-API-Key: <ключ>" \
     --data-urlencode "q=Челябинск ул. Чичерина 37Б" \
     --data-urlencode "limit=3"

{
  "status": "ok",
  "data": [
    {
      "label": "ул. Чичерина, 37Б, Челябинск",
      "display_name": "37Б, улица Чичерина, Калининский район, Челябинск, ...",
      "lat": 55.1751159,
      "lon": 61.3034954,
      "type": "house",
      "importance": 0.521
    }
  ],
  "quota": { "limit": 50, "used": 4, "remaining": 46, "reset": "..." }
}

curl -G "https://api.medialan74.ru/api/v1/reverse" \
     -H "X-API-Key: <ключ>" \
     --data-urlencode "lat=55.1751159" \
     --data-urlencode "lon=61.3034954"

{
  "status": "ok",
  "data": {
    "label": "ул. Чичерина, 37Б, Челябинск",
    "display_name": "37Б, улица Чичерина, Калининский район, Челябинск, ...",
    "lat": 55.1751159,
    "lon": 61.3034954,
    "address": {
      "house_number": "37Б",
      "road": "улица Чичерина",
      "city": "Челябинск",
      "postcode": "454128",
      "country": "Россия"
    }
  },
  "quota": { "limit": 50, "used": 5, "remaining": 45, "reset": "..." }
}

{
  "status": "ok",
  "data": {
    "key_type": "demo",        // demo | subscription
    "tariff": null,            // basic | premium | premium_plus | null
    "daily_limit": 50,
    "used_today": 5,
    "remaining": 45,
    "reset": "2026-10-17T00:00:00+03:00",
    "key_status": "active"
  },
  "quota": { "limit": 50, "used": 5, "remaining": 45, "reset": "..." }
}

6. Ошибки

Все ошибки возвращаются в едином формате:

{
  "status": "error",
  "error": {
    "code": "quota_exceeded",
    "message": "Суточная квота запросов исчерпана. Лимит: 50 запросов/сутки."
  }
}

7. Примеры интеграции

JavaScript (fetch)

const API = "https://api.medialan74.ru/api/v1";
const KEY = "<ВАШ_КЛЮЧ>";

async function buildRoute(from, to) {
  const url = new URL(API + "/route");
  url.searchParams.set("from", from);   // "61.4030,55.1644"
  url.searchParams.set("to", to);
  url.searchParams.set("profile", "driving");

  const res = await fetch(url, { headers: { "X-API-Key": KEY } });
  const json = await res.json();

  if (json.status !== "ok") {
    throw new Error(json.error.message);
  }
  console.log("Расстояние, м:", json.data.distance);
  console.log("Время, сек:", json.data.duration);
  console.log("Остаток квоты:", json.quota.remaining);
  return json.data;
}

PHP (cURL)

$ch = curl_init('https://api.medialan74.ru/api/v1/route?' . http_build_query([
    'from' => '61.4030,55.1644',
    'to'   => '61.3750,55.1900',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: <ВАШ_КЛЮЧ>'],
]);
$response = json_decode(curl_exec($ch), true);

Python (requests)

import requests

r = requests.get(
    "https://api.medialan74.ru/api/v1/geocode",
    headers={"X-API-Key": "<ВАШ_КЛЮЧ>"},
    params={"q": "Челябинск ул. Чичерина 37Б", "limit": 3},
)
print(r.json()["data"][0]["label"])

8. Ограничения и рекомендации

• Границы данных. На данный момент маршрутизация работает только в пределах (Уральского федерального округа). Точки за пределами вернут ошибку построения маршрута.
• Производительность. Среднее время ответа route — десятки миллисекунд;
• Кэширование. Рекомендуем кэшировать одинаковые запросы на вашей стороне — это экономит квоту.
• Безопасность. Передавайте ключ только в заголовках; GET-параметр api_key предназначен для отладки.
• Честное использование. Квоты защищают сервис от перегрузки; при необходимости бо́льших лимитов — свяжитесь с администратором для перехода на тариф выше.