smart-google-maps-nestjs

Author: Nurul Islam Rimon
Repository: https://github.com/nurulislamrimon/smart-google-maps-nestjs

Production-grade NestJS module for Google Maps APIs.

Features

• Geocoding: Convert addresses to coordinates
• Reverse Geocoding: Convert coordinates to addresses
• Places Search: Search for places by query
• Place Details: Get detailed information about a place
• Distance Matrix: Calculate distance and duration between origins and destinations
• Directions: Get turn-by-turn directions
• Batch Geocode: Geocode multiple addresses
• Caching: Optional in-memory caching for API responses
• Rate Limiting: Prevent exceeding Google API quotas

Installation

npm install smart-google-maps-nestjs

Requirements

• NestJS 10+
• @nestjs/common
• @nestjs/config

Peer dependencies (must be installed):

npm install @nestjs/common @nestjs/config axios

Optional dependencies for caching:

npm install @nestjs/cache-manager cache-manager

Quick Start

1. Import the module

import { Module } from '@nestjs/common';
import { SmartGoogleMapsModule } from 'smart-google-maps-nestjs';

@Module({
  imports: [
    SmartGoogleMapsModule.forRoot({
      apiKey: process.env.GOOGLE_MAPS_API_KEY,
    }),
  ],
})
export class AppModule {}

2. Inject and use the service

import { Injectable } from '@nestjs/common';
import { GoogleMapsService } from 'smart-google-maps-nestjs';

@Injectable()
export class LocationService {
  constructor(private readonly mapsService: GoogleMapsService) {}

  async getCoordinates(address: string) {
    return this.mapsService.geocode(address);
  }
}

Configuration Options

interface SmartGoogleMapsOptions {
  apiKey: string;
  baseUrl?: string;           // Custom API base URL
  timeout?: number;            // Request timeout in ms (default: 10000)
  cache?: {
    enabled: boolean;         // Enable/disable caching
    ttl: number;              // Cache TTL in ms (default: 3600000)
  };
  rateLimit?: {
    enabled: boolean;         // Enable/disable rate limiting
    maxRequests: number;      // Max requests per window
    windowMs: number;         // Time window in ms
  };
}

API Reference

Geocoding

Convert an address to latitude/longitude coordinates.

const result = await mapsService.geocode('1600 Amphitheatre Parkway, Mountain View, CA');
// Returns: { lat: 37.422..., lng: -122.084..., formattedAddress: '...' }

Reverse Geocoding

Convert coordinates to a human-readable address.

const result = await mapsService.reverseGeocode(37.422, -122.084);
// Returns: { formattedAddress: '...', addressComponents: [...], placeId: '...' }

Places Search

Search for places by query.

const results = await mapsService.searchPlaces('restaurants in San Francisco');
// Returns: PlaceSearchResult[]

Place Details

Get detailed information about a place.

const details = await mapsService.getPlace('ChIJN1t_tDeuEmsRUsoyG69frY4');
// Returns: PlaceDetailsResult

Distance Matrix

Calculate distance and duration between two points.

const result = await mapsService.distance('San Francisco, CA', 'Los Angeles, CA', {
  mode: 'driving',
  units: 'metric',
});
// Returns: { distance: '615 km', distanceValue: 615000, duration: '...', durationValue: ... }

Directions

Get turn-by-turn directions.

const result = await mapsService.directions({
  origin: 'San Francisco, CA',
  destination: 'Los Angeles, CA',
  mode: 'driving',
});
// Returns: DirectionsResult with routes, legs, and steps

Batch Geocode

Geocode multiple addresses in batch.

const results = await mapsService.batchGeocode([
  '1600 Amphitheatre Parkway, Mountain View, CA',
  '1 Apple Park Way, Cupertino, CA',
]);
// Returns: GeocodingResult[]

Clear Cache

Clear the cache manually.

await mapsService.clearCache();

Async Configuration

For dynamic or environment-based configuration:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { SmartGoogleMapsModule } from 'smart-google-maps-nestjs';

@Module({
  imports: [
    ConfigModule.forRoot(),
    SmartGoogleMapsModule.forRootAsync({
      useFactory: (configService: ConfigService) => ({
        apiKey: configService.get<string>('GOOGLE_MAPS_API_KEY'),
        cache: {
          enabled: true,
          ttl: 3600000,
        },
        rateLimit: {
          enabled: true,
          maxRequests: 50,
          windowMs: 1000,
        },
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Full Example

import { Module } from '@nestjs/common';
import { SmartGoogleMapsModule, GoogleMapsService } from 'smart-google-maps-nestjs';

@Module({
  imports: [
    SmartGoogleMapsModule.forRoot({
      apiKey: process.env.GOOGLE_MAPS_API_KEY!,
      cache: {
        enabled: true,
        ttl: 3600000, // 1 hour
      },
      rateLimit: {
        enabled: true,
        maxRequests: 50,
        windowMs: 1000,
      },
    }),
  ],
})
export class AppModule {}

License

MIT