Converter Package API

The @route-optimization/converter package provides utilities to convert between Google Maps DirectionsResult and Route Optimization data structures.

Installation

npm install @route-optimization/converter

Works with any framework or vanilla JavaScript.

Functions

toDirectionsResult()

Convert Route Optimization data to Google Maps DirectionsResult format.

function toDirectionsResult(
  routes: Route[],
  options?: ConversionOptions
): google.maps.DirectionsResult;

Parameters:

Parameter	Type	Required	Description
routes	Route[]	Yes	Array of routes to convert
options	ConversionOptions	No	Conversion options

ConversionOptions:

interface ConversionOptions {
  travelMode?: google.maps.TravelMode;
  optimizeWaypoints?: boolean;
  provideRouteAlternatives?: boolean;
  unitSystem?: google.maps.UnitSystem;
}

Returns: google.maps.DirectionsResult

Example:

import { toDirectionsResult } from '@route-optimization/converter';

const routes = [
  {
    id: 'route-1',
    vehicleId: 'vehicle-1',
    stops: [
      {
        id: 'start',
        location: { lat: 13.7563, lng: 100.5018 },
        type: 'START',
        sequence: 0,
      },
      {
        id: 'delivery-1',
        location: { lat: 13.7467, lng: 100.5342 },
        type: 'DELIVERY',
        sequence: 1,
      },
    ],
    totalDistance: 5420,
    totalDuration: 900,
  },
];

const directionsResult = toDirectionsResult(routes, {
  travelMode: google.maps.TravelMode.DRIVING,
  optimizeWaypoints: true,
});

// Use with Google Maps DirectionsRenderer
const directionsRenderer = new google.maps.DirectionsRenderer();
directionsRenderer.setDirections(directionsResult);

fromDirectionsResult()

Convert Google Maps DirectionsResult to Route Optimization format.

function fromDirectionsResult(
  directionsResult: google.maps.DirectionsResult,
  options?: ParseOptions
): Route[];

Parameters:

Parameter	Type	Required	Description
directionsResult	google.maps.DirectionsResult	Yes	Google Maps directions
options	ParseOptions	No	Parsing options

ParseOptions:

interface ParseOptions {
  vehicleId?: string;
  routeIdPrefix?: string;
  stopIdPrefix?: string;
  includeStopDetails?: boolean;
}

Property	Type	Default	Description
vehicleId	string	'vehicle-1'	Vehicle ID for routes
routeIdPrefix	string	'route-'	Prefix for route IDs
stopIdPrefix	string	'stop-'	Prefix for stop IDs
includeStopDetails	boolean	true	Include detailed stop info

Returns: Route[]

Example:

import { fromDirectionsResult } from '@route-optimization/converter';

const directionsService = new google.maps.DirectionsService();

const request = {
  origin: 'Bangkok, Thailand',
  destination: 'Pattaya, Thailand',
  waypoints: [{ location: 'Chonburi, Thailand' }, { location: 'Si Racha, Thailand' }],
  travelMode: google.maps.TravelMode.DRIVING,
};

directionsService.route(request, (result, status) => {
  if (status === google.maps.DirectionsStatus.OK) {
    const routes = fromDirectionsResult(result, {
      vehicleId: 'truck-001',
      routeIdPrefix: 'delivery-',
      includeStopDetails: true,
    });

    console.log(routes);
    // Routes in Route Optimization format
  }
});

encodePolyline()

Encode an array of coordinates to Google polyline format.

function encodePolyline(coordinates: LatLng[]): string;

Parameters:

Parameter	Type	Required	Description
coordinates	LatLng[]	Yes	Array of coordinates

Returns: string - Encoded polyline

Example:

import { encodePolyline } from '@route-optimization/converter';

const coordinates = [
  { lat: 13.7563, lng: 100.5018 },
  { lat: 13.7467, lng: 100.5342 },
  { lat: 13.7279, lng: 100.5241 },
];

const encoded = encodePolyline(coordinates);
console.log(encoded);
// Output: "_p~iF~ps|U_ulLnnqC_mqNvxq`@"

decodePolyline()

Decode a Google polyline string to coordinates.

function decodePolyline(encoded: string): LatLng[];

Parameters:

Parameter	Type	Required	Description
encoded	string	Yes	Encoded polyline string

Returns: LatLng[] - Array of coordinates

Example:

import { decodePolyline } from '@route-optimization/converter';

const encoded = '_p~iF~ps|U_ulLnnqC_mqNvxq`@';
const coordinates = decodePolyline(encoded);

console.log(coordinates);
// Output: [
//   { lat: 13.7563, lng: 100.5018 },
//   { lat: 13.7467, lng: 100.5342 },
//   { lat: 13.7279, lng: 100.5241 }
// ]

calculateRouteDistance()

Calculate total distance of a route from DirectionsResult.

function calculateRouteDistance(
  directionsResult: google.maps.DirectionsResult,
  routeIndex?: number
): number;

Parameters:

Parameter	Type	Default	Description
directionsResult	google.maps.DirectionsResult	-	Directions result
routeIndex	number	0	Route index

Returns: number - Distance in meters

Example:

import { calculateRouteDistance } from '@route-optimization/converter';

const distance = calculateRouteDistance(directionsResult);
console.log(`Total distance: ${distance / 1000} km`);

calculateRouteDuration()

Calculate total duration of a route from DirectionsResult.

function calculateRouteDuration(
  directionsResult: google.maps.DirectionsResult,
  routeIndex?: number
): number;

Parameters:

Parameter	Type	Default	Description
directionsResult	google.maps.DirectionsResult	-	Directions result
routeIndex	number	0	Route index

Returns: number - Duration in seconds

Example:

import { calculateRouteDuration } from '@route-optimization/converter';

const duration = calculateRouteDuration(directionsResult);
console.log(`Total duration: ${duration / 60} minutes`);

extractWaypoints()

Extract waypoints from DirectionsResult.

function extractWaypoints(
  directionsResult: google.maps.DirectionsResult,
  routeIndex?: number
): LatLng[];

Parameters:

Parameter	Type	Default	Description
directionsResult	google.maps.DirectionsResult	-	Directions result
routeIndex	number	0	Route index

Returns: LatLng[] - Array of waypoint coordinates

Example:

import { extractWaypoints } from '@route-optimization/converter';

const waypoints = extractWaypoints(directionsResult);
console.log(`Route has ${waypoints.length} waypoints`);

Examples

Convert Routes to DirectionsResult

import { toDirectionsResult } from '@route-optimization/converter';
import { RouteMapView } from '@route-optimization/react';

function MyMapComponent({ routes }) {
  const directionsResult = toDirectionsResult(routes, {
    travelMode: google.maps.TravelMode.DRIVING,
    unitSystem: google.maps.UnitSystem.METRIC,
  });

  return (
    <RouteMapView
      apiKey="YOUR_API_KEY"
      route={routes[0]}
      center={{ lat: 13.7563, lng: 100.5018 }}
      zoom={12}
    />
  );
}

Parse Google Directions to Routes

import { fromDirectionsResult } from '@route-optimization/converter';

async function getDirections() {
  const directionsService = new google.maps.DirectionsService();

  const request = {
    origin: { lat: 13.7563, lng: 100.5018 },
    destination: { lat: 13.6904, lng: 100.7501 },
    waypoints: [{ location: { lat: 13.7278, lng: 100.5241 } }],
    travelMode: google.maps.TravelMode.DRIVING,
  };

  return new Promise((resolve, reject) => {
    directionsService.route(request, (result, status) => {
      if (status === google.maps.DirectionsStatus.OK) {
        const routes = fromDirectionsResult(result, {
          vehicleId: 'van-001',
          routeIdPrefix: 'delivery-',
          includeStopDetails: true,
        });
        resolve(routes);
      } else {
        reject(new Error(`Directions request failed: ${status}`));
      }
    });
  });
}

const routes = await getDirections();
console.log(routes);

Polyline Encoding/Decoding

import { encodePolyline, decodePolyline } from '@route-optimization/converter';

// Store route as encoded polyline (saves space)
const route = {
  id: 'route-1',
  vehicleId: 'vehicle-1',
  stops: [...],
  polyline: encodePolyline([
    { lat: 13.7563, lng: 100.5018 },
    { lat: 13.7467, lng: 100.5342 },
    { lat: 13.7279, lng: 100.5241 },
  ]),
};

// Later, decode for display
const coordinates = decodePolyline(route.polyline);
console.log(`Route has ${coordinates.length} points`);

Route Statistics

import {
  calculateRouteDistance,
  calculateRouteDuration,
  extractWaypoints,
} from '@route-optimization/converter';

function displayRouteInfo(directionsResult: google.maps.DirectionsResult) {
  const distance = calculateRouteDistance(directionsResult);
  const duration = calculateRouteDuration(directionsResult);
  const waypoints = extractWaypoints(directionsResult);

  return {
    distanceKm: (distance / 1000).toFixed(2),
    durationMin: (duration / 60).toFixed(0),
    waypointCount: waypoints.length,
  };
}

const info = displayRouteInfo(directionsResult);
console.log(`
  Distance: ${info.distanceKm} km
  Duration: ${info.durationMin} minutes
  Waypoints: ${info.waypointCount}
`);

Bi-directional Conversion

import {
  toDirectionsResult,
  fromDirectionsResult,
} from '@route-optimization/converter';

// Route Optimization → Google Maps
const routes = [...]; // Your routes
const directionsResult = toDirectionsResult(routes);

// Display with Google Maps DirectionsRenderer
const renderer = new google.maps.DirectionsRenderer();
renderer.setDirections(directionsResult);

// Google Maps → Route Optimization
const parsedRoutes = fromDirectionsResult(directionsResult);

// Both formats are now available
console.log('Original routes:', routes);
console.log('Parsed routes:', parsedRoutes);

Integration with Route Optimization

import { fromDirectionsResult } from '@route-optimization/converter';
import { RouteMap } from '@route-optimization/vanilla';

async function displayOptimizedRoute() {
  // Get directions from Google Maps
  const directionsService = new google.maps.DirectionsService();

  const request = {
    origin: 'Bangkok, Thailand',
    destination: 'Pattaya, Thailand',
    waypoints: [{ location: 'Chonburi, Thailand' }, { location: 'Si Racha, Thailand' }],
    optimizeWaypoints: true, // Google optimizes order
    travelMode: google.maps.TravelMode.DRIVING,
  };

  directionsService.route(request, (result, status) => {
    if (status === google.maps.DirectionsStatus.OK) {
      // Convert to Route Optimization format
      const routes = fromDirectionsResult(result, {
        vehicleId: 'delivery-van-1',
      });

      // Display with Route Optimization
      const routeMap = new RouteMap({
        apiKey: 'YOUR_API_KEY',
        container: 'map',
      });

      routeMap.initialize().then(() => {
        routeMap.renderRoute(routes[0]);
      });
    }
  });
}

TypeScript Support

Full type definitions included:

import type { ConversionOptions, ParseOptions } from '@route-optimization/converter';

import {
  toDirectionsResult,
  fromDirectionsResult,
  encodePolyline,
  decodePolyline,
} from '@route-optimization/converter';

const options: ConversionOptions = {
  travelMode: google.maps.TravelMode.DRIVING,
  optimizeWaypoints: true,
};

const parseOptions: ParseOptions = {
  vehicleId: 'truck-001',
  routeIdPrefix: 'route-',
  includeStopDetails: true,
};

Error Handling

import { toDirectionsResult } from '@route-optimization/converter';

try {
  const directionsResult = toDirectionsResult(routes);
  // Use directionsResult
} catch (error) {
  if (error instanceof Error) {
    console.error('Conversion failed:', error.message);

    if (error.message.includes('empty')) {
      console.log('No routes to convert');
    } else if (error.message.includes('stops')) {
      console.log('Invalid stops data');
    }
  }
}

Common Use Cases

1. Display Google Directions with Route Optimization UI

const directionsResult = /* from Google Maps API */;
const routes = fromDirectionsResult(directionsResult);

// Use with Route Optimization components
<RouteMapView route={routes[0]} />

2. Save Routes in Compact Format

const route = /* your route */;
const encoded = encodePolyline(route.stops.map(s => s.location));

// Store in database (much smaller than JSON)
await database.save({ routeId: route.id, polyline: encoded });

3. Optimize Waypoints with Google, Display with Route Optimization

// Get optimized route from Google
const directionsResult = await getOptimizedDirections(stops);

// Convert to Route Optimization format
const routes = fromDirectionsResult(directionsResult);

// Display with custom UI
const routeMap = new RouteMap({ ... });
routeMap.renderRoute(routes[0]);

Next Steps

• Core Package API
• Vanilla Package API
• Advanced Examples