В разработке
Fastify Module · TypeScript · OpenStreetMap

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

Переиспользуемый модуль геолокации для встраивания в любое Fastify 5.x приложение. Геокодирование, reverse geocoding, расстояния — всё через единое API.

📖 Документация 🔗 GitHub
🚧
API в разработке. Модуль будет доступен по адресу https://geo-module.e-replika.ru/api — следите за обновлениями.

Возможности

📍
Геокодирование
Адрес или название → координаты. Поддержка фильтров по странам, bounding box, языку ответа.
🔄
Reverse Geocoding
Координаты → читаемый адрес. 18 уровней детализации от дома до страны.
📏
Расчёт расстояний
Haversine distance между двумя точками. Поддержка профилей: driving, walking, cycling.
In-memory кэш
TTL-кэш на все запросы к Nominatim. Cache hit rate видно в метриках. Настраиваемый TTL.
📊
Prometheus метрики
HTTP histogram, geocode counters, cache hit/miss, provider latency — всё в /api/metrics.
🔌
Fastify Plugin
Встраивается в любое Fastify 5.x приложение через app.register(geoPlugin).

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

integration-example.ts
// Встраивание как Fastify-плагин
import { geoPlugin } from '@portfolio/geo';

await app.register(geoPlugin, {
  baseUrl: 'http://geo-module.e-replika.ru',
});

// Теперь app.geo — готовый GeoClient
app.get('/location', async (req) => {
  const results = await app.geo.geocode(req.query.address);
  return results;
});

// Или напрямую через HTTP-клиент
import { GeoClient } from '@portfolio/geo';
const geo = new GeoClient({ baseUrl: '...' });

const address = await geo.reverse(55.7558, 37.6173);
const dist    = await geo.distance(55.75, 37.62, 59.93, 30.32);

Эндпоинты

GET
/api/geo/geocode?q={address}
Геокодирование — адрес/POI → список координат с деталями
GET
/api/geo/reverse?lat={lat}&lon={lon}
Обратное геокодирование — координаты → полный адрес
GET
/api/geo/distance?lat1=&lon1=&lat2=&lon2=
Расстояние между двумя точками (Haversine / OSRM)
GET
/api/health
Health check — статус сервиса, uptime, состояние кэша
GET
/api/metrics
Prometheus scrape endpoint (только localhost)
GET
/api/docs
Swagger UI — интерактивная документация OpenAPI 3.0

Стек

Fastify 5.x TypeScript Node.js 22 prom-client ESM (type: module) Nominatim / OSM Swagger / OpenAPI 3.0 pino logger Docker alpine vitest

Метрики (Prometheus)

geo_geocode_requests_total
counterby type+result
geo_http_request_duration_seconds
histogram9 buckets
geo_cache_hits_total
counterby operation
geo_geocode_provider_latency
histogramnominatim
geo_cache_size
gaugeentries
geo_provider_errors_total
counterby provider