Me3ka — API Reference

Аутентификация

Все запросы к API требуют передачи API-ключа. Ключ передаётся в заголовке X-API-Key или query-параметре api_key.

Заголовок

X-API-Key: me3ka_abc123def456

Для эндпоинтов личного кабинета используется JWT-токен в заголовке Authorization: Bearer <token>. Токен выдаётся при входе (POST /api/auth/login) и действует 24 часа. Для обновления используйте refresh-токен.

POST /api/auth/register

Регистрация нового пользователя.

Параметр	Тип	Описание
email	string	Email (обязательный)
password	string	Пароль, мин. 6 символов
name	string	Имя пользователя
company	string?	Название компании (опционально)

Ответ

{
  "access_token": "eyJ...",
  "refresh_token": "rt_abc123...",
  "user": { "id": 1, "email": "[email protected]", "name": "Иван", "role": "user" }
}

POST /api/auth/login

Вход в систему.

Параметр	Тип	Описание
email	string	Email
password	string	Пароль

POST /api/auth/refresh

Обновление access-токена.

Параметр	Тип	Описание
refresh_token	string	Refresh-токен, выданный при логине

Коды ошибок

API возвращает стандартные HTTP-коды и JSON с описанием ошибки.

Код	Значение	Описание
200	OK	Успешный запрос
400	Bad Request	Отсутствует обязательный параметр
401	Unauthorized	Неверный или отсутствующий ключ/токен
403	Forbidden	Нет доступа (лимит исчерпан)
404	Not Found	Ресурс не найден
429	Too Many Requests	Превышен rate limit (10 req/s)
500	Server Error	Внутренняя ошибка сервера

Пример ошибки

{
  "error": "Missing required parameter: q"
}

GET/api/geocode

Прямое геокодирование — поиск координат по текстовому адресу. Ищет по OSM (places, buildings, POIs, roads) и ФИАС ГАР. Использует pg_trgm для нечёткого поиска.

Параметр	Тип	Описание
q	string	Текст запроса (обязательный). Например: «Ростов-на-Дону Большая Садовая 12»
limit	int	Количество результатов (1–20, по умолчанию 5)

Запрос

GET /api/geocode?q=Москва+Тверская+1&limit=3

Ответ

{
  "results": [
    {
      "name": "г Москва, ул Тверская, д 1",
      "lat": 55.7558,
      "lon": 37.6173,
      "type": "fias",
      "score": 0.92
    }
  ],
  "query": "Москва Тверская 1",
  "count": 1,
  "time_ms": 87
}

GET/api/reverse

Обратное геокодирование — поиск адреса по координатам. Находит ближайшее здание, дорогу или населённый пункт.

Параметр	Тип	Описание
lat	float	Широта (обязательный)
lon	float	Долгота (обязательный)

Запрос

GET /api/reverse?lat=47.2357&lon=39.7015

Ответ

{
  "address": "ул. Большая Садовая, 12",
  "city": "Ростов-на-Дону",
  "lat": 47.2357,
  "lon": 39.7015,
  "distance_m": 15.2
}

GET/api/poi/search

Поиск точек интереса (POI) по тексту в заданном радиусе от указанных координат.

Параметр	Тип	Описание
q	string	Текст поиска (обязательный)
lat	float	Широта центра поиска
lon	float	Долгота центра поиска
radius	int	Радиус поиска в метрах (по умолчанию 1000)
limit	int	Максимум результатов (по умолчанию 20)

GET/api/organizations/search

Поиск организаций по названию, категории или адресу. База: 100 000+ организаций.

Параметр	Тип	Описание
q	string	Текст поиска (обязательный)
lat	float	Широта (для сортировки по расстоянию)
lon	float	Долгота
radius	int	Радиус в метрах (по умолчанию 5000)
category	string	Фильтр по категории
limit	int	Максимум результатов (по умолчанию 20)

GET/api/poi/{id}

Получение детальной информации о точке интереса по ID.

GET/api/organizations/{id}

Детальная информация об организации: название, адрес, телефон, часы работы, категории.

GET/api/route

Построение автомобильного маршрута через OSRM. Возвращает геометрию, расстояние и время.

Параметр	Тип	Описание
start_lat	float	Широта начальной точки
start_lon	float	Долгота начальной точки
end_lat	float	Широта конечной точки
end_lon	float	Долгота конечной точки

Запрос

GET /api/route?start_lat=47.23&start_lon=39.70&end_lat=47.28&end_lon=39.75

Ответ

{
  "distance_km": 8.4,
  "duration_min": 15.2,
  "geometry": { "type": "LineString", "coordinates": [[39.70, 47.23], ...] }
}

POST/api/ai/chat

AI-ассистент для вопросов о местах, маршрутах и геоданных. Использует LLM через OpenRouter API.

Параметр	Тип	Описание
message	string	Сообщение пользователя
lat	float?	Текущая широта пользователя (для контекста)
lon	float?	Текущая долгота

Запрос

POST /api/ai/chat
{
  "message": "Где поесть хинкали в Ростове?",
  "lat": 47.2357,
  "lon": 39.7015
}

POST/api/smart/search

Умный поиск с пониманием естественного языка. Автоматически определяет тип запроса (адрес, организация, маршрут).

Параметр	Тип	Описание
query	string	Поисковый запрос на естественном языке

GET/tiles/{source}/{z}/{x}/{y}

Векторные тайлы в формате MVT (Mapbox Vector Tiles). Подаются через Martin тайл-сервер. Используйте с MapLibre GL JS.

Параметр	Тип	Описание
source	string	Имя источника (osm_buildings, osm_roads, osm_pois, osm_places, osm_water, osm_landuse)
z	int	Уровень масштабирования (0–22)
x	int	Номер тайла по X
y	int	Номер тайла по Y

Важно: URL тайлов не использует расширение .pbf. Кеширование: 1 час (Cache-Control).

Пример MapLibre GL JS

map.addSource('buildings', {
  type: 'vector',
  tiles: ['https://me3ka.ru/tiles/osm_buildings/{z}/{x}/{y}'],
  minzoom: 12,
  maxzoom: 16
});

map.addLayer({
  id: 'buildings-fill',
  type: 'fill',
  source: 'buildings',
  'source-layer': 'osm_buildings',
  paint: { 'fill-color': '#6c63ff', 'fill-opacity': 0.4 }
});

GET/api/health

Проверка работоспособности API. Не требует авторизации.

Ответ

{ "status": "ok" }

GET/api/stats

Статистика по базе данных: количество зданий, дорог, адресов, организаций.

Ответ

{
  "buildings": 1380753,
  "roads": 334314,
  "pois": 62622,
  "places": 4910,
  "fias_addresses": 29839438,
  "organizations": 100047
}

GET/api/openapi.json

OpenAPI 3.0 спецификация для автоматической генерации клиентов (Swagger, OpenAPI Generator).