@redonvn/geocoding-sdk

Thư viện TypeScript SDK định vị địa lý (Geocoding & Reverse Geocoding) và phân rã địa chỉ thông minh cho Việt Nam và quốc tế, thiết kế độc lập, zero-dependency, theo chuẩn Multi-Driver Architecture (OpenStreetMap Nominatim, Goong Maps, Google Maps, Custom HTTP Enterprise Services).

Tích hợp sẵn bộ chuyển đổi chuẩn (Converter) cho Ahamove (tọa độ GPS lat, lng, waypoints) và GHN (phân rã Tỉnh, Quận, Phường, mã code).

🌟 Tính Năng Nổi Bật

• 100% Zero-Dependency: Chỉ dựa trên Native fetch của Node.js 18+ và Web standard.
• Đa Nhà Cung Cấp (Multi-Driver Engine):
  • NominatimDriver: OpenStreetMap miễn phí 100%, tuân thủ rate-limit 1 req/s, bắt buộc User-Agent.
  • GoongDriver: Chuyên biệt địa chỉ ngõ, hẻm, số nhà Việt Nam.
  • GoogleMapsDriver: Chuẩn toàn cầu của Google Geocoding API.
  • CustomHttpDriver: Cắm rút linh hoạt endpoint nội bộ của doanh nghiệp với JSON path mapping.
• Fallback Chain & Auto-Retry: Tự động chuyển tiếp sang Driver phụ khi Driver chính hết quota hoặc không có kết quả.
• Bộ Nhớ Đệm Hiệu Năng Cao (In-Memory Cache): Hỗ trợ TTL và giới hạn kích thước (LRU pruning) để tiết kiệm quota và tăng tốc độ phản hồi.
• Bộ Chuyển Đổi Logistics Vận Chuyển:
  • toAhamoveWaypoint(result, contact): Trả về object waypoint path cho Ahamove API v3.
  • toGhnAddress(result, contact): Bóc tách to_name, to_phone, to_address, Tỉnh/Quận/Phường cho GHN.

📦 Cài Đặt

# Trong monorepo RedAI
npm install @redonvn/geocoding-sdk

🚀 Hướng Dẫn Sử Dụng Nhanh

1. Khởi tạo mặc định với OpenStreetMap (Miễn phí 100%)

import { GeocodingClient } from '@redonvn/geocoding-sdk';

const client = GeocodingClient.createDefault({
  userAgent: 'MyLogisticsApp/1.0 ([email protected])',
});

// Tra cứu địa chỉ tự do (Forward Geocoding)
const results = await client.search('Landmark 81 Bình Thạnh Hồ Chí Minh');
console.log(results[0]);
/*
{
  provider: 'nominatim',
  latitude: 10.795083,
  longitude: 106.721799,
  formattedAddress: 'Landmark 81, 720A, Điện Biên Phủ, Phường 22, Bình Thạnh, Thành phố Hồ Chí Minh',
  components: {
    houseNumber: '720A',
    road: 'Điện Biên Phủ',
    ward: '22',
    district: 'Bình Thạnh',
    province: 'Hồ Chí Minh'
  }
}
*/

2. Định vị ngược từ tọa độ GPS (Reverse Geocoding)

const location = await client.reverse({
  lat: 10.795083,
  lng: 106.721799,
});
console.log(location?.formattedAddress);

3. Tích hợp Driver riêng (Custom HTTP Driver) và Fallback Chain

import { GeocodingClient, NominatimDriver, CustomHttpDriver } from '@redonvn/geocoding-sdk';

const client = new GeocodingClient({
  primaryDriver: 'my-custom-service',
  fallbackChain: ['nominatim'],
});

// Đăng ký custom service nội bộ
client.registerDriver(
  new CustomHttpDriver({
    name: 'my-custom-service',
    searchUrl: 'https://internal-api.mycompany.vn/v1/geocode?query={query}&limit={limit}',
    mapping: {
      resultsPath: 'data.places',
      latPath: 'latitude',
      lngPath: 'longitude',
      formattedAddressPath: 'displayAddress',
      roadPath: 'street',
      wardPath: 'ward',
      districtPath: 'district',
      provincePath: 'city',
    },
  })
);

// Đăng ký Nominatim làm fallback
client.registerDriver(
  new NominatimDriver({
    userAgent: 'MyEnterpriseApp/1.0',
  })
);

const results = await client.search('72 Lê Thánh Tôn Quận 1');

4. Chuyển đổi trực tiếp cho Ahamove & GHN

import { toAhamoveWaypoint, toGhnAddress } from '@redonvn/geocoding-sdk';

const geoResult = results[0];

// Dùng cho Ahamove
const ahamovePoint = toAhamoveWaypoint(geoResult, {
  name: 'Nguyễn Văn A',
  mobile: '0901234567',
  remarks: 'Giao giờ hành chính',
  cod: 200000,
});

// Dùng cho GHN
const ghnAddress = toGhnAddress(geoResult, {
  name: 'Nguyễn Văn A',
  phone: '0901234567',
});

📄 License

MIT © Redon