# VRP API — Vietmap API Playground

> Assigns many stops across a fleet, respecting capacity and time windows.

The VRP API (vehicle routing) assigns many deliveries and pick-ups to many vehicles at once, respecting each vehicle’s capacity, customer time windows, vehicle skills (refrigerated, heavy trucks…) and priorities. It returns each vehicle’s route in driving order with arrival times and the load on board; anything that could not be placed is listed as unassigned, showing whether vehicles are short or constraints too tight.

What it is for:
- Daily last-mile planning for a fleet.
- Deliveries within promised time slots.
- Pick up at A, deliver to B (shipments).
- Assigning field technicians by skill.

- Interactive page: https://tools.vietmap.vn/playground/en/vrp
- Endpoint: `POST /api/vrp?api-version=1.1` on `https://maps.vietmap.vn`
- Official documentation: https://maps.vietmap.vn/docs/map-api/vrp/
- API key: every request needs the `apikey` parameter. Samples use `YOUR_API_KEY` as the placeholder — when integrating, read the key from an environment variable (e.g. `VIETMAP_API_KEY`). Get a key at https://maps.vietmap.vn/console-v2/consumers
- Error codes: `401` wrong API key · `403` key restricted to another domain/IP · `423` API not enabled for the key's consumer, or out of credit (body contains "exceeded credit") · `429` rate limit exceeded.

## Code samples

### cURL

```bash
curl -X POST 'https://maps.vietmap.vn/api/vrp?api-version=1.1&apikey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "jobs": [
    {
      "id": 1,
      "location": [
        106.70592,
        10.79628
      ],
      "service": 600,
      "description": "Cửa hàng Bình Thạnh",
      "delivery": [
        3
      ],
      "time_windows": [
        [
          28800,
          39600
        ]
      ]
    },
    {
      "id": 2,
      "location": [
        106.7066,
        10.80189
      ],
      "service": 900,
      "description": "Siêu thị mini Điện Biên Phủ",
      "delivery": [
        4
      ]
    },
    {
      "id": 3,
      "location": [
        106.68982,
        10.80159
      ],
      "service": 600,
      "description": "Quán ăn Phú Nhuận",
      "delivery": [
        2
      ],
      "time_windows": [
        [
          32400,
          43200
        ]
      ]
    },
    {
      "id": 4,
      "location": [
        106.695,
        10.785
      ],
      "service": 300,
      "description": "Nhà khách Quận 3",
      "delivery": [
        1
      ]
    },
    {
      "id": 5,
      "location": [
        106.712,
        10.7905
      ],
      "service": 600,
      "description": "Kho lẻ Thủ Đức",
      "delivery": [
        3
      ],
      "time_windows": [
        [
          46800,
          57600
        ]
      ]
    },
    {
      "id": 6,
      "location": [
        106.6835,
        10.7925
      ],
      "service": 300,
      "description": "Tiệm tạp hoá Gò Vấp",
      "delivery": [
        2
      ]
    },
    {
      "id": 7,
      "location": [
        106.6961,
        10.7826
      ],
      "service": 600,
      "description": "Nhà hàng Nguyễn Đình Chiểu",
      "delivery": [
        2
      ],
      "time_windows": [
        [
          50400,
          61200
        ]
      ]
    },
    {
      "id": 8,
      "location": [
        106.7047,
        10.7877
      ],
      "service": 300,
      "description": "Chung cư Bình Thạnh",
      "delivery": [
        1
      ]
    }
  ],
  "vehicles": [
    {
      "id": 1,
      "description": "Xe tải nhỏ 1",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        12
      ]
    },
    {
      "id": 2,
      "description": "Xe tải nhỏ 2",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        12
      ]
    },
    {
      "id": 3,
      "description": "Xe giao hàng nhỏ",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        4
      ]
    }
  ]
}'
```

### JavaScript

```javascript
// In production, read the key from an environment variable instead.
const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams([
  ["api-version", "1.1"],
  ["apikey", API_KEY],
]);

const body = {
  "jobs": [
    {
      "id": 1,
      "location": [
        106.70592,
        10.79628
      ],
      "service": 600,
      "description": "Cửa hàng Bình Thạnh",
      "delivery": [
        3
      ],
      "time_windows": [
        [
          28800,
          39600
        ]
      ]
    },
    {
      "id": 2,
      "location": [
        106.7066,
        10.80189
      ],
      "service": 900,
      "description": "Siêu thị mini Điện Biên Phủ",
      "delivery": [
        4
      ]
    },
    {
      "id": 3,
      "location": [
        106.68982,
        10.80159
      ],
      "service": 600,
      "description": "Quán ăn Phú Nhuận",
      "delivery": [
        2
      ],
      "time_windows": [
        [
          32400,
          43200
        ]
      ]
    },
    {
      "id": 4,
      "location": [
        106.695,
        10.785
      ],
      "service": 300,
      "description": "Nhà khách Quận 3",
      "delivery": [
        1
      ]
    },
    {
      "id": 5,
      "location": [
        106.712,
        10.7905
      ],
      "service": 600,
      "description": "Kho lẻ Thủ Đức",
      "delivery": [
        3
      ],
      "time_windows": [
        [
          46800,
          57600
        ]
      ]
    },
    {
      "id": 6,
      "location": [
        106.6835,
        10.7925
      ],
      "service": 300,
      "description": "Tiệm tạp hoá Gò Vấp",
      "delivery": [
        2
      ]
    },
    {
      "id": 7,
      "location": [
        106.6961,
        10.7826
      ],
      "service": 600,
      "description": "Nhà hàng Nguyễn Đình Chiểu",
      "delivery": [
        2
      ],
      "time_windows": [
        [
          50400,
          61200
        ]
      ]
    },
    {
      "id": 8,
      "location": [
        106.7047,
        10.7877
      ],
      "service": 300,
      "description": "Chung cư Bình Thạnh",
      "delivery": [
        1
      ]
    }
  ],
  "vehicles": [
    {
      "id": 1,
      "description": "Xe tải nhỏ 1",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        12
      ]
    },
    {
      "id": 2,
      "description": "Xe tải nhỏ 2",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        12
      ]
    },
    {
      "id": 3,
      "description": "Xe giao hàng nhỏ",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        4
      ]
    }
  ]
};

const response = await fetch(`https://maps.vietmap.vn/api/vrp?${params}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
});
if (!response.ok) {
  throw new Error(`Vietmap ${response.status}: ${await response.text()}`);
}
const data = await response.json();
console.log(data);
```

### Python

```python
import requests

# In production, read the key from an environment variable instead.
API_KEY = "YOUR_API_KEY"

params = [
    ("api-version", "1.1"),
    ("apikey", API_KEY),
]

body = {
    "jobs": [
        {
            "id": 1,
            "location": [
                106.70592,
                10.79628,
            ],
            "service": 600,
            "description": "Cửa hàng Bình Thạnh",
            "delivery": [
                3,
            ],
            "time_windows": [
                [
                    28800,
                    39600,
                ],
            ],
        },
        {
            "id": 2,
            "location": [
                106.7066,
                10.80189,
            ],
            "service": 900,
            "description": "Siêu thị mini Điện Biên Phủ",
            "delivery": [
                4,
            ],
        },
        {
            "id": 3,
            "location": [
                106.68982,
                10.80159,
            ],
            "service": 600,
            "description": "Quán ăn Phú Nhuận",
            "delivery": [
                2,
            ],
            "time_windows": [
                [
                    32400,
                    43200,
                ],
            ],
        },
        {
            "id": 4,
            "location": [
                106.695,
                10.785,
            ],
            "service": 300,
            "description": "Nhà khách Quận 3",
            "delivery": [
                1,
            ],
        },
        {
            "id": 5,
            "location": [
                106.712,
                10.7905,
            ],
            "service": 600,
            "description": "Kho lẻ Thủ Đức",
            "delivery": [
                3,
            ],
            "time_windows": [
                [
                    46800,
                    57600,
                ],
            ],
        },
        {
            "id": 6,
            "location": [
                106.6835,
                10.7925,
            ],
            "service": 300,
            "description": "Tiệm tạp hoá Gò Vấp",
            "delivery": [
                2,
            ],
        },
        {
            "id": 7,
            "location": [
                106.6961,
                10.7826,
            ],
            "service": 600,
            "description": "Nhà hàng Nguyễn Đình Chiểu",
            "delivery": [
                2,
            ],
            "time_windows": [
                [
                    50400,
                    61200,
                ],
            ],
        },
        {
            "id": 8,
            "location": [
                106.7047,
                10.7877,
            ],
            "service": 300,
            "description": "Chung cư Bình Thạnh",
            "delivery": [
                1,
            ],
        },
    ],
    "vehicles": [
        {
            "id": 1,
            "description": "Xe tải nhỏ 1",
            "profile": "car",
            "start": [
                106.7,
                10.79,
            ],
            "end": [
                106.7,
                10.79,
            ],
            "capacity": [
                12,
            ],
        },
        {
            "id": 2,
            "description": "Xe tải nhỏ 2",
            "profile": "car",
            "start": [
                106.7,
                10.79,
            ],
            "end": [
                106.7,
                10.79,
            ],
            "capacity": [
                12,
            ],
        },
        {
            "id": 3,
            "description": "Xe giao hàng nhỏ",
            "profile": "car",
            "start": [
                106.7,
                10.79,
            ],
            "end": [
                106.7,
                10.79,
            ],
            "capacity": [
                4,
            ],
        },
    ],
}

response = requests.post("https://maps.vietmap.vn/api/vrp", params=params, json=body, timeout=60)
response.raise_for_status()
print(response.json())
```

## AI prompt

A ready-made prompt for a coding assistant (ChatGPT, Claude, Copilot…) to write the integration:

````text
I need to integrate Vietmap's VRP API (api-version 1.1) into my application.

Official documentation: https://maps.vietmap.vn/docs/map-api/vrp/

Here is a sample request that works in the Vietmap API Playground:

POST https://maps.vietmap.vn/api/vrp?api-version=1.1&apikey=YOUR_API_KEY

Body (JSON):
```json
{
  "jobs": [
    {
      "id": 1,
      "location": [
        106.70592,
        10.79628
      ],
      "service": 600,
      "description": "Cửa hàng Bình Thạnh",
      "delivery": [
        3
      ],
      "time_windows": [
        [
          28800,
          39600
        ]
      ]
    },
    {
      "id": 2,
      "location": [
        106.7066,
        10.80189
      ],
      "service": 900,
      "description": "Siêu thị mini Điện Biên Phủ",
      "delivery": [
        4
      ]
    },
    {
      "id": 3,
      "location": [
        106.68982,
        10.80159
      ],
      "service": 600,
      "description": "Quán ăn Phú Nhuận",
      "delivery": [
        2
      ],
      "time_windows": [
        [
          32400,
          43200
        ]
      ]
    },
    {
      "id": 4,
      "location": [
        106.695,
        10.785
      ],
      "service": 300,
      "description": "Nhà khách Quận 3",
      "delivery": [
        1
      ]
    },
    {
      "id": 5,
      "location": [
        106.712,
        10.7905
      ],
      "service": 600,
      "description": "Kho lẻ Thủ Đức",
      "delivery": [
        3
      ],
      "time_windows": [
        [
          46800,
          57600
        ]
      ]
    },
    {
      "id": 6,
      "location": [
        106.6835,
        10.7925
      ],
      "service": 300,
      "description": "Tiệm tạp hoá Gò Vấp",
      "delivery": [
        2
      ]
    },
    {
      "id": 7,
      "location": [
        106.6961,
        10.7826
      ],
      "service": 600,
      "description": "Nhà hàng Nguyễn Đình Chiểu",
      "delivery": [
        2
      ],
      "time_windows": [
        [
          50400,
          61200
        ]
      ]
    },
    {
      "id": 8,
      "location": [
        106.7047,
        10.7877
      ],
      "service": 300,
      "description": "Chung cư Bình Thạnh",
      "delivery": [
        1
      ]
    }
  ],
  "vehicles": [
    {
      "id": 1,
      "description": "Xe tải nhỏ 1",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        12
      ]
    },
    {
      "id": 2,
      "description": "Xe tải nhỏ 2",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        12
      ]
    },
    {
      "id": 3,
      "description": "Xe giao hàng nhỏ",
      "profile": "car",
      "start": [
        106.7,
        10.79
      ],
      "end": [
        106.7,
        10.79
      ],
      "capacity": [
        4
      ]
    }
  ]
}
```

Parameters in use:
- api-version = 1.1

Write code in [my language / framework] that calls this API, with these requirements:
1. Read the API key from the VIETMAP_API_KEY environment variable; never hard-code it.
2. Send the parameters in the query string exactly as in the sample; repeated parameters (such as `point`) must keep their order.
3. Handle Vietmap's HTTP errors:
   - 401: the API key is wrong or revoked.
   - 403: the key is restricted to a domain / IP that does not match.
   - 423: the API is not enabled for the key's consumer, OR the account is out of credit — tell them apart by the response body ("exceeded credit" means out of credit).
   - 429: rate limit exceeded — retry with increasing backoff.
4. Set a request timeout, and define types (type / interface / dataclass) for the response.

If unsure about a field name, look it up in the documentation linked above instead of guessing.
````

## Reopen this exact request in the Playground

https://tools.vietmap.vn/playground/en/vrp?sample=last-mile