QuickRoute GeoRecommendations

Overview

QuickRoute GeoRecommendations is a TypeScript library that provides address autocomplete suggestions based on partial inputs. It currently integrates with TomTom API and OpenStreetMap, offering:

• Typed and structured responses
• Support for LTS Node.js environments
• Australian address filtering
• Extensibility for future geolocation providers

Features

✅ Address autocomplete via TomTom and OpenStreetMap
✅ Structured location data (country, state, municipality, etc.)
✅ Australian address filtering (for TomTom provider)
✅ Supports multiple geolocation providers
✅ Well-tested with high coverage
✅ Supports easy map local cache

Installation

Refer NPM Package in : https://www.npmjs.com/package/quickroute-geo-recommendations

To install the package, run:

npm install quickroute-geo-recommendations

Usage

1. Import the Library & Initialize a Provider

const { getProvider, ProviderType } = require("quickroute-geo-recommendations");

// ✅ Using TomTom Provider (Requires API key)
const tomtom = getProvider(ProviderType.TomTomMapsProvider, "your-api-key");

tomtom
  .getSuggestions("crescent")
  .then((result) => console.log("TomTom Results:", result))
  .catch(console.error);

// ✅ Using OpenStreetMap Provider (No API key required)
const osm = getProvider(ProviderType.OpenStreetMapsProvider);

osm
  .getSuggestions("crescent")
  .then((result) => console.log("OSM Results:", result))
  .catch(console.error);

API Reference

getSuggestions(query: string): Promise<AddressSuggestion[]>

Retrieves a list of address suggestions based on the query.

Example Response

[
  {
    "address": "123 Crescent St",
    "latitude": -33.8688,
    "longitude": 151.2093,
    "country": "Australia",
    "state": "NSW",
    "municipality": "Sydney",
    "postcode": "2000",
    "placeId": "123"
  }
]

AddressSuggestion Type

type AddressSuggestion = {
  address: string;
  latitude: number | null;
  longitude: number | null;
  country?: string;
  state?: string;
  municipality?: string;
  postcode?: string;
  placeId?: string;
  boundingBox?: [number, number, number, number];
};

Testing

To run the test suite:

npm run test

Test Coverage Report

----------------------------|---------|----------|---------|---------|-------------------
File                        | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------------------------|---------|----------|---------|---------|-------------------
All files                   |     100 |     85.1 |     100 |     100 |
 providers                  |     100 |    82.05 |     100 |     100 |
  baseGeoProvider.ts        |     100 |    82.35 |     100 |     100 | 19,37-38
  openStreetMapsProvider.ts |     100 |      100 |     100 |     100 |
  tomtomMapsProvider.ts     |     100 |    63.63 |     100 |     100 | 43-52
 services                   |     100 |      100 |     100 |     100 |
  getProvider.ts            |     100 |      100 |     100 |     100 |
 utils                      |     100 |      100 |     100 |     100 |
  error.ts                  |     100 |      100 |     100 |     100 |
----------------------------|---------|----------|---------|---------|-------------------
Test Suites: 3 passed, 3 total
Tests:       17 passed, 17 total
Snapshots:   0 total
Time:        0.534 s, estimated 1 s

Future Enhancements

• Improve filtering on the API results to make it fast and rank based
• Deepdive into possible edge cases and error scenarios
• Support for more geolocation providers (Google Maps, etc.)
• Enhance rate limiting
• End to End tests and integration tests
• Host on API Gateway, Lambda and enable caching using Redis
• Docker image for easy testing
• Logging and monitoring using AWS Cloudwatch Insights Dashboard
• Use current location, autocomplete ranking
• User intent-based address prediction
• Support batch processing
• Extend it to multiple countries with flexible language, output limits

License

This package is licensed under the MIT License.