Python SDK

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

Installation

Install the SDK using your preferred Python package manager:

pip
poetry
pipenv

pip install --pre solvice-vrp-solver

poetry add solvice-vrp-solver --allow-prereleases

pipenv install --pre solvice-vrp-solver

The --pre flag is currently required as the package is in pre-release status.

Quick Start

Get up and running with the VRP Solver in minutes:

from solvice_vrp_solver import SolviceVrpSolver

client = SolviceVrpSolver(api_key="your_api_key")

# Solve a simple routing problem
solution = client.vrp.sync_solve({
    "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}
        }]
    }]
})

print(solution.routes)

Key Features

Type Safety

Full type definitions for all request parameters and response fields

Async Support

Native async/await support with both httpx and optional aiohttp backends

Pythonic Interface

Follows Python conventions with snake_case methods and proper error handling

Auto Retry

Built-in retry logic with configurable attempts for resilient integrations

Configuration

Configure the SDK client with these options:

from solvice_vrp_solver import SolviceVrpSolver

client = SolviceVrpSolver(
    api_key="your_api_key",          # Required: Your API key
    max_retries=2,                   # Optional: Number of retry attempts (default: 2)
    timeout=60.0,                    # Optional: Request timeout in seconds (default: 60.0)
    # Additional configuration options available
)

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

Advanced Usage

Asynchronous Client

For better performance with multiple requests, use the async client:

import asyncio
from solvice_vrp_solver import AsyncSolviceVrpSolver

async def main():
    client = AsyncSolviceVrpSolver(api_key="your_api_key")
    
    # Submit the job asynchronously
    response = await client.vrp.solve({
        "jobs": [...],
        "resources": [...],
        "options": {
            "maxSolvingTime": 300  # 5 minutes
        }
    })
    
    job_id = response.job_id
    
    # Check status
    status = await client.vrp.jobs.status(job_id)
    
    if status.status == "SOLVED":
        # Retrieve solution
        solution = await client.vrp.jobs.solution(job_id)
        print(solution)

# Run the async function
asyncio.run(main())

Error Handling

The SDK provides comprehensive error handling:

from solvice_vrp_solver import SolviceVrpSolver
from solvice_vrp_solver.exceptions import (
    BadRequestError,
    AuthenticationError,
    APIConnectionError
)

client = SolviceVrpSolver(api_key="your_api_key")

try:
    solution = client.vrp.sync_solve({...})
except BadRequestError as e:
    print(f"Invalid request: {e.message}")
    print(f"Details: {e.body}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except APIConnectionError as e:
    print(f"Connection failed: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Using with Real Road Distances

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

solution = client.vrp.sync_solve({
    "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
    }
})

Python Version Support

The SDK supports multiple Python versions:

Python 3.8+
Type Hints

Minimum supported version:

# Compatible with Python 3.8 and above
from solvice_vrp_solver import SolviceVrpSolver

Full type hint support:

from typing import Dict, List, Any
from solvice_vrp_solver import SolviceVrpSolver

def optimize_routes(jobs: List[Dict[str, Any]]) -> Dict[str, Any]:
    client = SolviceVrpSolver(api_key="your_api_key")
    return client.vrp.sync_solve({"jobs": jobs, "resources": [...]})

Complete Example

Here’s a comprehensive example showcasing various SDK features:

import asyncio
import os
from solvice_vrp_solver import AsyncSolviceVrpSolver

async def optimize_delivery_routes():
    client = AsyncSolviceVrpSolver(
        api_key=os.environ.get("SOLVICE_API_KEY"),
        max_retries=3,
        timeout=120.0  # 2 minutes
    )
    
    try:
        solution = await client.vrp.sync_solve({
            "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
        for route in solution.routes:
            print(f"Route for {route.resource_name}:")
            for stop in route.stops:
                print(f"- {stop.job_name} at {stop.arrival}")

        # Check for unassigned jobs
        if solution.unassigned:
            print(f"Unassigned jobs: {solution.unassigned}")

    except Exception as error:
        print(f"Optimization failed: {error}")

# Run the optimization
asyncio.run(optimize_delivery_routes())

API Methods

The SDK provides access to all VRP Solver endpoints:

Core Methods

sync_solve() - 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
demo() - Get a demo request for testing

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

Integration with Data Science Libraries

The Python SDK works seamlessly with popular data science libraries:

import pandas as pd
from solvice_vrp_solver import SolviceVrpSolver

# Load jobs from a CSV file
jobs_df = pd.read_csv('deliveries.csv')

# Convert to VRP format
jobs = jobs_df.to_dict('records')

# Optimize routes
client = SolviceVrpSolver(api_key="your_api_key")
solution = client.vrp.sync_solve({
    "jobs": jobs,
    "resources": [...]
})

# Convert solution back to DataFrame for analysis
routes_df = pd.DataFrame([
    {
        'job_name': stop.job_name,
        'resource_name': route.resource_name,
        'arrival_time': stop.arrival,
        'sequence': i
    }
    for route in solution.routes
    for i, stop in enumerate(route.stops)
])

print(routes_df.head())

Resources

PyPI Package

View on Python Package Index

GitHub Repository

View source code and contribute

API Reference

Complete API documentation

Support

Get help from our team

Platform

VRP API

Fill API

Installation

Quick Start

Key Features

Type Safety

Async Support

Pythonic Interface

Auto Retry

Configuration

Advanced Usage

Asynchronous Client

Error Handling

Using with Real Road Distances

Python Version Support

Complete Example

API Methods

Core Methods

Advanced Methods

Integration with Data Science Libraries

Resources

PyPI Package

GitHub Repository

API Reference

Support

​Installation

​Quick Start

​Key Features

Type Safety

Async Support

Pythonic Interface

Auto Retry

​Configuration

​Advanced Usage

​Asynchronous Client

​Error Handling

​Using with Real Road Distances

​Python Version Support

​Complete Example

​API Methods

​Core Methods

​Advanced Methods

​Integration with Data Science Libraries

​Resources

PyPI Package

GitHub Repository

API Reference

Support

Installation

Quick Start

Key Features

Configuration

Advanced Usage

Asynchronous Client

Error Handling

Using with Real Road Distances

Python Version Support

Complete Example

API Methods

Core Methods

Advanced Methods

Integration with Data Science Libraries

Resources