sadiq-address-search

TypeScript Library for Address Search

This library provides a robust and efficient solution for finding complete addresses using a partial address. It is currently configured to use the TomTom API. However, it is designed to be extensible, maintainable, and easily consumable in any LTS Node.js environment.

To change the address search provider, all we need to do is implement the AddressService interface. In the default implementation, this library provides TomTomAddressService, which returns addresses (as Address objects) from the TomTom API. The constructor of this class defaults to Australia (AU), but can be changed to any other country.

The test suite achieves 100% statement coverage.

This package can be found at NPM: https://www.npmjs.com/package/sadiq-address-search

Implementation choices

Why not use an SDK provided by TomTom?

There are 3 SDKs provided by TomTom, for Android, iOS and Web. The web one is suitable for the front-end and my attempts to get it working for the backend were not successful.

Why not use the Autocomplete API by TomTom?

TomTom provides an Autocomplete API, however its results were not suitable to help complete a partially provided address. In my brief exploration of this API, it didn't seem to provide the best experience in completing an address.

Project Setup

Prerequisites

• Node.js (v18 or later recommended)
• npm or yarn

Installation

1. Clone this repository
2. Install dependencies:

   npm install

3. Build with:

   npm run build

Getting a TomTom API Key

1. Sign up for a free account at TomTom Developer Portal
2. Create a new project and generate an API key
3. Copy the API key to your .env file

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run start - Run the compiled application
• npm run dev - Run the application using ts-node (without compiling)
• npm run lint - Lint the codebase
• npm run test - Run the test suite

Project Structure

• src/ - Source code directory
  • index.ts - Main entry point
  • services/ - Service modules
    • addressService.ts - Defines the Address interfaces and types. Use only these types to keep your implementation generic.
    • tomtomService.ts - TomTom API integration. This implements the interfaces and returns the types defined in the addressService.ts file.
• release/ - Compiled JavaScript (generated after build)

Usage in Another Project

To use this library in another project, follow these steps:

1. Install the library:

   npm install sadiq-tomtom-address-search

2. Import and use the TomTomAddressService in your project:

   import { TomTomAddressService } from "sadiq-address-search";
   
   const apiKey = 'your_api_key_here';
   const addressService = new TomTomAddressService(apiKey); // Will default to Australia
   
   addressService.searchAddress('Level 18/1 Nicholson St')
       .then(results => {
           console.log('Search results:', results);
           if (results && results.length > 0) {
               console.log(results);
           }
       })
       .catch(error => {
           console.error('Error while searching:', error);
       });

License

This project is licensed under the ISC License.