PlanSolve for Python

Official Python client for the PlanSolve optimization API. One typed client covers three solvers (field service routing, professional-services task assignment, and shift scheduling) with built-in polling and clean error messages.

Installation

pip install plansolve

Requires Python 3.8+ and requests 2.31+. Type hints are bundled.

Quick start

from plansolve import PlanSolveClient

client = PlanSolveClient(api_key="YOUR_API_KEY")

request = {
    "vehicles": [
        {
            "id": "tech1",
            "location": [40.7128, -74.0060],
            "skills": ["repair"],
            "shifts": [
                {"id": "morning", "minStartTime": "2026-04-02T08:00:00", "maxEndTime": "2026-04-02T17:00:00"}
            ],
        }
    ],
    "visits": [
        {
            "id": "visit1",
            "name": "AC Repair - Downtown Office",
            "location": [40.7589, -73.9851],
            "serviceDuration": "PT60M",
            "priority": "HIGH",
            "requiredSkills": ["repair"],
            "timeWindows": [
                {"minStartTime": "2026-04-02T09:00:00", "maxEndTime": "2026-04-02T17:00:00"}
            ],
        }
    ],
}

# Submit and block until the optimized plan is ready
result = client.field_service.start_and_wait_for_completion(request)

for vehicle in result.vehicles:
    print(f"Vehicle {vehicle.id}: {len(vehicle.visits)} visits")

Requests accept a plain dict (as above) or the typed dataclasses (FieldServiceRequest, Vehicle, Visit, ...).

Solvers

One client, three solvers. All share the same submit, poll, result workflow:

Every solver client exposes the same methods:

{solver} is fieldservice, professionalservices or shift. The result types are FieldServiceResultResponse, ProfessionalServicesResultResponse and ShiftResultResponse; each gets a client-side job_id stamped after parsing.

Polling

The wait helpers sleep poll_interval_ms before each status check and stop as soon as the status reports solving false and solverStatus NOT_SOLVING (a score is not required). The defaults are 5000 ms between polls and 150 polls (12.5 minutes), which covers the server's 10-minute cap on a solve. A value of 0 or less for either argument falls back to the default.

# Stop early and keep the best plan found so far
best = client.shift.stop(job_id)

# Inspect which constraints drive the score
analysis = client.field_service.analyze(job_id)

Unassigned work parses cleanly: a field service visit the solver could not place comes back with vehicle, arrival_time, departure_time, start_service_time and driving_time_seconds_from_previous_standstill set to None.

Configuration

Pass your API key to the constructor: PlanSolveClient(api_key="..."). It is sent as the X-API-KEY header on every request.

Error handling

The SDK never prints to stdout or stderr; everything is reported through exceptions:

import requests

try:
    result = client.field_service.start_and_wait_for_completion(request)
except requests.HTTPError as e:
    print(e.response.status_code, e)
except ValueError as e:
    print(e)

Documentation

Full guides, per-solver data models, and parameter reference live on the docs site:

• Field Service: https://getplansolve.com/docs/fieldservice/sdk/python
• Professional Services: https://getplansolve.com/docs/professionalservices/sdk/python
• Shift: https://getplansolve.com/docs/shiftsolver/sdk/python

Package: PyPI

License

Apache-2.0. See LICENSE.