AddressKit

TypeScript library for address resolution, normalization, and enrichment using OpenStreetMap's Nominatim API.

Leer en Español

Features

• Address Resolution: Transforms partial input into standardized shipping data.
• Smart Caching: Built-in LRU memory cache with configurable TTL to improve performance and respect API limits.

Installation

npm install address-kit

Basic Usage

import { AddressKit } from 'address-kit';

const kit = new AddressKit();

async function run() {
  const result = await kit.resolve({
    street: 'Gran Vía',
    city: 'Madrid',
    country: 'Spain'
  });

  if (result.found && result.data) {
    console.log('Address:', result.data.formattedAddress);
    console.log('Coordinates:', result.data.coordinates);
  }
}

run();

Configuration

AddressKit can be initialized with custom options:

const kit = new AddressKit({
  language: 'en',        // Result language (ISO 639-1)
  cacheTtl: 3600000      // TTL in milliseconds (0 to disable)
});

Custom Providers

You can implement the GeoProvider interface to use other services:

const kit = new AddressKit({
  provider: 'custom',
  providerInstance: new YourCustomProvider()
});

License

MIT

Data Sources and Attribution

This library uses the Nominatim API provided by OpenStreetMap. By using this library, you agree to comply with:

• Nominatim Usage Policy
• OpenStreetMap Attribution Requirements

Please ensure you provide appropriate credit in your own application.