TypeScript SDK

The official Solvice VRP Solver SDK is now available! Install it today to streamline your route optimization integrations.

Installation

Install the SDK using your preferred package manager:

npm
yarn
pnpm

npm install solvice-vrp-solver

yarn add solvice-vrp-solver

pnpm add solvice-vrp-solver

Quick Start

Get up and running with the VRP Solver in minutes:

import SolviceVrpSolver from 'solvice-vrp-solver';

const client = new SolviceVrpSolver({
  apiKey: process.env.SOLVICE_API_KEY, // Required
});

// Solve a simple routing problem
const solution = await client.vrp.syncSolve({
  jobs: [
    { 
      name: 'delivery-1',
      location: { latitude: 51.0500, longitude: 3.7300 },
      duration: 900 // 15 minutes
    },
    { 
      name: 'delivery-2',
      location: { latitude: 51.0543, longitude: 3.7174 },
      duration: 600 // 10 minutes
    }
  ],
  resources: [{ 
    name: 'vehicle-1', 
    shifts: [{ 
      from: '2024-01-15T08:00:00Z', 
      to: '2024-01-15T17:00:00Z',
      start: { latitude: 51.0543, longitude: 3.7174 }
    }] 
  }],
});

console.log(solution.routes);

Key Features

Type Safety

Full TypeScript support with comprehensive type definitions for all request and response objects

Auto Retry

Built-in retry logic with configurable attempts for resilient integrations

Modern Runtime Support

Works in Node.js, Deno, Bun, browsers, and Cloudflare Workers

Error Handling

Typed error responses with detailed debugging information

Configuration

Configure the SDK client with these options:

const client = new SolviceVrpSolver({
  apiKey: process.env.SOLVICE_API_KEY,     // Required: Your API key
  maxRetries: 2,                           // Optional: Number of retry attempts (default: 2)
  timeout: 60000,                          // Optional: Request timeout in ms (default: 60000)
  logLevel: 'info',                        // Optional: 'debug' | 'info' | 'warn' | 'error' | 'off'
});

Never hardcode your API key. Always use environment variables or secure key management systems.

Advanced Usage

Asynchronous Solve with Polling

For large routing problems, use the asynchronous solve method:

// Submit the job
const { jobId } = await client.vrp.solve({
  jobs: [...],
  resources: [...],
  options: {
    maxSolvingTime: 300 // 5 minutes
  }
});

// Check status
const status = await client.vrp.jobs.status(jobId);

if (status.status === 'SOLVED') {
  // Retrieve solution
  const solution = await client.vrp.jobs.solution(jobId);
  console.log(solution);
}

Error Handling

The SDK provides typed error responses for better debugging:

import { BadRequestError, AuthenticationError } from 'solvice-vrp-solver';

try {
  const solution = await client.vrp.syncSolve({...});
} catch (error) {
  if (error instanceof BadRequestError) {
    console.error('Invalid request:', error.message);
    console.error('Details:', error.body);
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Using with Real Road Distances

Enable real-world routing distances instead of straight-line calculations:

const solution = await client.vrp.syncSolve({
  jobs: [...],
  resources: [...],
  options: {
    euclidian: false,    // Use real road networks instead of straight-line
    routingEngine: 'OSM', // OSM, TOMTOM, or GOOGLE
    traffic: 1.3,        // 30% traffic factor
    polylines: true      // Include route geometries for mapping
  }
});

Runtime Support

The SDK supports multiple JavaScript runtimes:

Node.js
Deno
Bun
Browser

Requires Node.js 20 LTS or later:

// CommonJS
const SolviceVrpSolver = require('solvice-vrp-solver');

// ESM
import SolviceVrpSolver from 'solvice-vrp-solver';

Works with Deno v1.28.0 or later:

import SolviceVrpSolver from "npm:solvice-vrp-solver";

Compatible with Bun 1.0 or later:

import SolviceVrpSolver from 'solvice-vrp-solver';

Use with modern browsers via a bundler:

import SolviceVrpSolver from 'solvice-vrp-solver';

Complete Example

Here’s a comprehensive example showcasing various SDK features:

import SolviceVrpSolver from 'solvice-vrp-solver';

const client = new SolviceVrpSolver({
  apiKey: process.env.SOLVICE_API_KEY,
  maxRetries: 3,
  timeout: 120000, // 2 minutes
  logLevel: 'info'
});

async function optimizeDeliveryRoutes() {
  try {
    const solution = await client.vrp.syncSolve({
      resources: [{
        name: 'vehicle-1',
        shifts: [{
          from: '2024-01-15T08:00:00Z',
          to: '2024-01-15T17:00:00Z',
          start: { latitude: 51.0543, longitude: 3.7174 },
          end: { latitude: 51.0543, longitude: 3.7174 }
        }],
        capacity: [100],
        tags: ['refrigerated'],
        breaks: [{
          duration: 1800, // 30 minutes
          windows: [{
            from: '2024-01-15T12:00:00Z',
            to: '2024-01-15T13:00:00Z'
          }]
        }]
      }],
      jobs: [
        {
          name: 'customer-123',
          location: { latitude: 51.0500, longitude: 3.7300 },
          duration: 900,
          load: [20],
          priority: 10,
          tags: [{ name: 'refrigerated', hard: true }],
          windows: [{
            from: '2024-01-15T09:00:00Z',
            to: '2024-01-15T11:00:00Z'
          }]
        },
        {
          name: 'customer-456',
          location: { latitude: 51.0600, longitude: 3.7400 },
          duration: 600,
          load: [15],
          priority: 5,
          windows: [{
            from: '2024-01-15T14:00:00Z',
            to: '2024-01-15T16:00:00Z'
          }]
        }
      ],
      options: {
        euclidian: false,
        routingEngine: 'OSM',
        traffic: 1.2,
        maxSolvingTime: 60
      }
    });

    // Process the solution
    solution.routes.forEach(route => {
      console.log(`Route for ${route.resourceName}:`);
      route.stops.forEach(stop => {
        console.log(`- ${stop.jobName} at ${stop.arrival}`);
      });
    });

    // Check for unassigned jobs
    if (solution.unassigned.length > 0) {
      console.warn('Unassigned jobs:', solution.unassigned);
    }

  } catch (error) {
    console.error('Optimization failed:', error);
  }
}

optimizeDeliveryRoutes();

API Methods

The SDK provides access to all VRP Solver endpoints:

Core Methods

syncSolve() - Synchronous solving for smaller problems
solve() - Asynchronous solving for larger problems
jobs.status() - Check job status
jobs.solution() - Retrieve solution

Advanced Methods

evaluate() - Evaluate an existing solution
suggest() - Get improvement suggestions
jobs.explanation() - Get detailed explanations

For problems with more than 100 jobs or complex constraints, use the asynchronous solve() method to avoid timeouts.

Resources

GitHub Repository

View source code and contribute

npm Package

View on npm registry

API Reference

Complete API documentation

Support

Get help from our team

Platform

VRP API

Fill API

Installation

Quick Start

Key Features

Type Safety

Auto Retry

Modern Runtime Support

Error Handling

Configuration

Advanced Usage

Asynchronous Solve with Polling

Error Handling

Using with Real Road Distances

Runtime Support

Complete Example

API Methods

Core Methods

Advanced Methods

Resources

GitHub Repository

npm Package

API Reference

Support

​Installation

​Quick Start

​Key Features

Type Safety

Auto Retry

Modern Runtime Support

Error Handling

​Configuration

​Advanced Usage

​Asynchronous Solve with Polling

​Error Handling

​Using with Real Road Distances

​Runtime Support

​Complete Example

​API Methods

​Core Methods

​Advanced Methods

​Resources

GitHub Repository

npm Package

API Reference

Support

Installation

Quick Start

Key Features

Configuration

Advanced Usage

Asynchronous Solve with Polling

Error Handling

Using with Real Road Distances

Runtime Support

Complete Example

API Methods

Core Methods

Advanced Methods

Resources