Quickstart¶

This tutorial demonstrates how to get started quickly with the FastVRP API.

FastVRP solves vehicle routing problems asynchronously in three simple steps:

Submit a routing job
Check the job status
Obtain the result

Let's walk through each of the three steps below.

Setup¶

Before we start, you'll need the following:

A FastVRP account - Sign up here if you don't have an account yet.
An API key - Generate one here after logging in.

Submit a routing job¶

To submit a job, send a POST request to the /submit endpoint. Let's submit a simple routing job, with one vehicle that needs to serve one task. Save the following job data as request.json:

request.json

{
  "tasks": [
    {
      "id": "task",
      "location": {
        "latitude": 52.3676,
        "longitude": 4.9041
      }
    }
  ],
  "depots": [
    {
      "id": "depot",
      "location": {
        "latitude": 52.0907,
        "longitude": 5.1214
      }
    }
  ],
  "vehicle_types": [
    {
      "id": "vehicle_type",
      "start_depot": "depot",
      "end_depot": "depot",
      "num_available": 1,
      "shift": {
        "start": "2025-01-01T08:00:00",
        "end": "2025-01-01T18:00:00"
      }
    }
  ],
  "options": {
    "stop": {
      "seconds": 1,
      "type": "max_runtime"
    }
  }
}

Then, make the following request using your API key.

Request

curl https://fastvrp.routinglab.tech/api/v1/submit \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: $YOUR_API_KEY" \
  --data @request.json

This returns a response containing the job ID, which can be used later to retrieve the job's status and result.

Response

{
  "job_id": "77639186-16d0-48ea-a918-ed788c1b6b79"
}

Check the job status¶

To check a job's status, make a GET request to the /status/<job_id> endpoint with your job ID, like so:

Request

curl https://fastvrp.routinglab.tech/api/v1/status/$JOB_ID \
  --header "X-API-KEY: $YOUR_API_KEY"

This returns a response containing the job ID, as well as the job's status code.

Response

{
  "job_id": "77639186-16d0-48ea-a918-ed788c1b6b79",
  "status": 3
}

There are four job statuses:

SUBMITTED - Job has been submitted, but not yet executed.
IN_PROGRESS - Job is currently being executed.
COMPLETED - Job has finished execution.
ERRORED - Job has errored during execution.

Poll this endpoint every few seconds until the job has the COMPLETED or ERRORED status.

Obtain the result¶

When the job status is COMPLETED, make a GET request to the /result/<job_id> endpoint:

Request

curl -L https://fastvrp.routinglab.tech/api/v1/result/$JOB_ID \
  --header "X-API-KEY: $YOUR_API_KEY"

Note

The /result endpoint redirects to a Google Cloud Storage URL, where job results are stored. The -L flag tells curl to follow this redirect automatically.

This response contains the complete routing solution, including high-level summaries and detailed route plans.

Response

{
  "summary": {
    "total_cost": "90.01",
    "distance_cost": "88.54",
    "duration_cost": "1.47",
    "fixed_vehicle_cost": "0.00",
    "distance": 88538,
    "duration": "PT5297S",
    "travel_duration": "PT5297S",
    "service_duration": "P0D",
    "wait_duration": "P0D",
    "num_planned": 1,
    "num_unplanned": 0,
    "num_routes": 1,
    "load_duration": "P0D"
  },
  "routes": [
    {
      "summary": {
        "total_cost": "90.01",
        "distance_cost": "88.54",
        "duration_cost": "1.47",
        "fixed_vehicle_cost": "0.00",
        "distance": 88538,
        "duration": "PT5297S",
        "travel_duration": "PT5297S",
        "service_duration": "P0D",
        "wait_duration": "P0D",
        "start_time": "2025-01-01T08:00:00",
        "end_time": "2025-01-01T09:28:17",
        "num_tasks": 1,
        "num_stops": 3,
        "slack_duration": "PT30703S",
        "load_duration": "P0D"
      },
      "vehicle_type_id": "vehicle_type",
      "profile": "car",
      "stops": [
        {
          "location": {
            "latitude": 52.0907,
            "longitude": 5.1214
          },
          "location_id": "depot",
          "type": "depot",
          "start_time": "2025-01-01T08:00:00",
          "end_time": "2025-01-01T08:00:00",
          "duration": "P0D",
          "wait_duration": "P0D",
          "travel_duration": "P0D",
          "distance": 0
        },
        {
          "location": {
            "latitude": 52.3676,
            "longitude": 4.9041
          },
          "location_id": "task",
          "type": "task",
          "start_time": "2025-01-01T08:43:51",
          "end_time": "2025-01-01T08:43:51",
          "duration": "P0D",
          "wait_duration": "P0D",
          "travel_duration": "PT2631S",
          "distance": 44198
        },
        {
          "location": {
            "latitude": 52.0907,
            "longitude": 5.1214
          },
          "location_id": "depot",
          "type": "depot",
          "start_time": "2025-01-01T09:28:17",
          "end_time": "2025-01-01T09:28:17",
          "duration": "P0D",
          "wait_duration": "P0D",
          "travel_duration": "PT2666S",
          "distance": 44340
        }
      ],
      "polyline": "<omitted>"
    }
  ],
  "unplanned": [],
  "job_id": "77639186-16d0-48ea-a918-ed788c1b6b79",
  "technical": {
    "runtime": 1.0,
    "iterations": 2000
  }
}

If the job status is ERRORED, then the response will instead contain an error message. We proactively monitor such failures, but please do let us know when this happens so that we can investigate the error further.

Next steps¶

This completes the quickstart tutorial. Check out the user guide next to learn more about using FastVRP, or see the API reference for the complete API specification.