Fastify 5 · TypeScript · Node.js 22 · OpenStreetMap

Геолокация
как микросервис

Переиспользуемый модуль геолокации для встраивания в любое Fastify-приложение. Геокодирование, маршруты, дорожная инфраструктура РФ, платные дороги, ДТП, погода.

80+
эндпоинтов
413
тестов
Redis
кэш
OSM
провайдер

Возможности

📍
Геокодирование
Адрес → координаты, reverse geocoding, autocomplete, batch (до 50 адресов), streaming NDJSON, async webhook.
🗺
Маршруты
Маршруты через точки, матрица расстояний N×M, изохроны зоны достижимости, encoded polyline.
🛣
Инфраструктура РФ
АПВГК (посты весового контроля), ФВФ-камеры, зоны контроля, поверки АРШИН/ГРСИ, реестр АСМАП.
💰
Платные дороги
М-11, М-12, ЦКАД, М-4 и другие. Тарифы по категориям ТС, расчёт стоимости проезда, ближайшие пункты.
⚠️
ДТП и аварийность
ДТП в радиусе (dtp-stat.ru), индекс опасности маршрута, кластеры аварийности на сетке.
🌦
Дорожная погода
Текущие условия и прогноз (Open-Meteo), риск гололёда/тумана/ветра, погода вдоль маршрута.
🏛
Субъекты РФ
Справочник 89+4 субъектов РФ с ОКАТО/ISO/ФО/часовыми поясами. Поиск по координатам и коду.
🔍
КЛАДР / Кадастр
Поиск адресов через КЛАДР-API (публичный), кадастровые данные Росреестра ПКК, иерархия адресов.
Кэш и Circuit Breaker
In-memory TTL или Redis. Circuit breaker для Nominatim. In-flight deduplication. Прогрев кэша при старте.

Использование

integration.ts
// Fastify-плагин — декоратор app.geo → GeoClient
import { geoPlugin, GeoClient } from '@portfolio/geo';

await app.register(geoPlugin, { baseUrl: 'https://geo-module.e-replika.ru' });
const results = await app.geo.geocode('Москва, Красная площадь');

// Или прямой HTTP-клиент (30+ методов)
const geo = new GeoClient({ baseUrl: 'https://geo-module.e-replika.ru' });

const address  = await geo.reverse(55.7558, 37.6173);
const route    = await geo.route({lat:55.75,lon:37.62}, {lat:59.93,lon:30.32});
const matrix   = await geo.matrix(origins, destinations);
const region   = await geo.regionByCoords(55.7558, 37.6173);
const risks    = await geo.accidentsNear(55.7558, 37.6173, 1000);

Эндпоинты

📍 Геокодирование 9
GET/api/geo/geocode
GET/api/geo/reverse
GET/api/geo/suggest
POST/api/geo/batch
POST/api/geo/reverse/batch
POST/api/geo/batch/stream
POST/api/geo/batch/async
GET/api/geo/places
🗺 Маршруты 7
GET/api/geo/route
POST/api/geo/route
POST/api/geo/matrix
GET/api/geo/isochrone
GET/api/geo/isochrone/multi
GET/api/geo/distance
GET/api/geo/nearest
🛠 Гео-утилиты 10
GET/api/geo/timezone
POST/api/geo/timezone/batch
GET/api/geo/convert
GET/api/geo/elevation
GET/api/geo/midpoint
GET/api/geo/bbox
POST/api/geo/geofence/check
POST/api/geo/cluster
POST/api/geo/polyline/encode
GET/api/geo/geohash/neighbors
📡 IP-геолокация 3
GET/api/geo/ip
GET/api/geo/ip/:ip
POST/api/geo/ip/batch
🏛 Субъекты РФ 6
GET/api/geo/russian-regions
GET/api/geo/russian-regions/districts
GET/api/geo/russian-regions/timezones
GET/api/geo/russian-regions/by-coords
GET/api/geo/russian-regions/near
GET/api/geo/russian-regions/:code
💰 Платные дороги 4
GET/api/geo/toll-roads/roads
GET/api/geo/toll-roads/tariffs/:roadId
GET/api/geo/toll-roads/calculate
GET/api/geo/toll-roads/near
⚖️ АПВГК / ФВФ 12
GET/api/geo/vgk/posts
GET/api/geo/vgk/near
GET/api/geo/vgk/calibrations
GET/api/geo/vgk/asmap
GET/api/geo/vgk/manufacturers
GET/api/geo/fvf/cameras
GET/api/geo/fvf/models
GET/api/geo/fvf/calibrations
⚠️ ДТП и погода 7
GET/api/geo/accidents/near
GET/api/geo/accidents/route-risk
GET/api/geo/accidents/hotspots
GET/api/geo/road-weather/current
GET/api/geo/road-weather/forecast
GET/api/geo/road-weather/risk
POST/api/geo/road-weather/route
🔍 КЛАДР / Кадастр 6
GET/api/geo/fias/search
GET/api/geo/fias/hierarchy/:code
GET/api/geo/fias/:code
GET/api/geo/cadastre/search
GET/api/geo/cadastre/near
GET/api/geo/cadastre/:cadNum
🌐 OSM / Overpass 4
GET/api/geo/overpass/cameras
GET/api/geo/overpass/weighbridges
POST/api/geo/overpass/query
GET/api/geo/cameras/moscow
📊 Система 5
GET/api/health
GET/api/metrics/json
GET/api/docs
GET/api/geo/playground
GET/api/geo/data-registry

Стек

Fastify 5.x TypeScript Node.js 22 prom-client ESM (type: module) Nominatim / OSM OSRM (опц.) Redis (опц.) Swagger / OpenAPI 3.0 pino logger MapLibre GL 4 Docker alpine vitest GitHub Actions

Метрики (Prometheus)

geo_http_request_duration_seconds
histogram9 buckets
geo_geocode_requests_total
countertype+result
geo_cache_hits_total
counterby operation
geo_geocode_provider_latency
histogramnominatim
geo_circuit_breaker_state
gauge0/1/2
geo_provider_errors_total
counterby provider