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 install 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.getStatus({ jobId });

if (status.status === 'SOLVED') {
  // Retrieve solution
  const solution = await client.vrp.getSolution({ 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:
Requires Node.js 20 LTS or later:
// CommonJS
const SolviceVrpSolver = require('solvice-vrp-solver');

// ESM
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
  • getStatus() - Check job status
  • getSolution() - Retrieve solution

​
Advanced Methods

  • evaluate() - Evaluate an existing solution
  • suggest() - Get improvement suggestions
  • explain() - 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