@geoapify/route-planner-sdk
Version:
A TypeScript SDK for the Geoapify Route Planner API that simplifies route optimization requests, and helps visualize and edit resulting routes.
249 lines (179 loc) • 13.5 kB
Markdown
# Geoapify Route Optimization SDK
The **Geoapify Route Optimization SDK** is a lightweight, dependency-free TypeScript library that simplifies building, executing requests, and modifying results for the [Geoapify Route Planner API](https://www.geoapify.com/route-planner-api/). It helps you easily implement advanced **route optimization** and delivery planning in both frontend (browser) and backend (Node.js) environments.
---
## Features
- Easy-to-use route optimization and delivery planning.
- Works in browser and Node.js environments.
- No dependencies and minimal package size.
- Modify and edit route results after planning.
---
## Installation
Install the SDK from NPM:
```bash
npm install @geoapify/route-planner-sdk
```
---
## Quick Start
### Getting API Key
To use the Route Optimization SDK, you need a valid **Geoapify API Key**.
1. Go to the [Geoapify page](https://www.geoapify.com/).
2. Sign up for a Geoapify account. No credit card is required.
3. Use the created by default or create a new API key.
You can start with the **Free Plan** which includes usage limits suitable for testing and small projects.
For commercial use and higher request volumes, consider upgrading your plan.
### Import the SDK
```ts
import RoutePlanner, { Agent, Job } from "@geoapify/route-planner-sdk";
const planner = new RoutePlanner({ apiKey: "YOUR_API_KEY" });
```
Or use in HTML:
```html
<script src="./node_modules/@geoapify/route-planner-sdk/dist/index.min.js"></script>
<script>
const planner = new RoutePlannerSDK.RoutePlanner({ apiKey: "YOUR_API_KEY" });
</script>
```
### Basic Route Optimization Example
```ts
await planner
.setMode("drive")
.addAgent(new Agent().setId("agent-1").setStartLocation(13.38, 52.52))
.addJob(new Job().setId("job-1").setLocation(13.39, 52.51))
.plan();
```
or
```ts
const routePlannerData: RoutePlannerInputData = {
agents: [...],
jobs: [...],
max_speed: 100
};
const planner = new RoutePlanner({apiKey: API_KEY}, routePlannerData);
```
---
## Advanced Usage
### Create Shipment / Delivery task
```ts
const planner = new RoutePlanner({apiKey: API_KEY});
planner.setMode("drive");
planner.addAgent(new Agent().setStartLocation(44.50485912329202, 40.177547000000004).addTimeWindow(0, 7200));
planner.addAgent(new Agent().setStartLocation(44.50485912329202, 40.177547000000004).addTimeWindow(0, 7200));
planner.addAgent(new Agent().setStartLocation(44.50485912329202, 40.177547000000004).addTimeWindow(0, 7200));
planner.addLocation(new Location().setId("warehouse-0").setLocation(44.5130974, 40.1766863));
planner.addShipment(new Shipment().setId("order-1")
.setDelivery(new ShipmentStep().setDuration(120).setLocation(44.50932929564537, 40.18686625))
.setPickup(new ShipmentStep().setDuration(120).setLocationIndex(0)));
planner.addShipment(new Shipment().setId("order-2")
.setDelivery(new ShipmentStep().setDuration(120).setLocation(44.511160727462574, 40.1816037))
.setPickup(new ShipmentStep().setDuration(120).setLocationIndex(0)));
planner.addAvoid(new Avoid().setType("tolls"));
planner.addAvoid(new Avoid().addValue(40.50485912329202, 42.177547000000004).setType("locations"));
planner.setTraffic("approximated")
planner.setType("short")
planner.setUnits("metric");
planner.setMaxSpeed(10)
const result = await planner.plan();
```
### Create job optimization task
```js
const planner = new RoutePlanner({apiKey: API_KEY});
planner.setMode("drive");
planner.addAgent(new Agent().setStartLocation(44.52566026661482, 40.1877687).addTimeWindow(0, 10800).setEndLocation(44.486653350000005, 40.18298485).setPickupCapacity(10000));
planner.addAgent(new Agent().setStartLocation(44.52244306971864, 40.1877687).addTimeWindow(0, 10800));
planner.addAgent(new Agent().setStartLocation(44.505007387303756, 40.1877687).addTimeWindow(0, 10800).setEndLocation(44.486653350000005, 40.18298485).setPickupCapacity(10000));
planner.addJob(new Job().setDuration(300).setPickupAmount(60).setLocation(44.50932929564537, 40.18686625));
planner.addJob(new Job().setDuration(200).setPickupAmount(20000).setLocation(44.50932929564537, 40.18686625));
planner.addJob(new Job().setDuration(300).setPickupAmount(10).setLocation(44.50932929564537, 40.18686625));
planner.addJob(new Job().setDuration(300).setPickupAmount(0).setLocation(44.50932929564537, 40.18686625));
const result = await planner.plan();
```
---
## Modifying Route Results
You can edit planned routes easily using `RoutePlannerResultEditor`.
### Assign jobs to the agent
```ts
const routeEditor = new RoutePlannerResultEditor(result);
await routeEditor.assignJobs('agent-a', ['job-2']);
let modifiedResult = routeEditor.getModifiedResult();
```
### Assign shipments to the agent
```ts
const routeEditor = new RoutePlannerResultEditor(result);
await routeEditor.assignShipments('agent-b', ['shipment-2']);
let modifiedResult = routeEditor.getModifiedResult();
```
### Remove jobs
```ts
const routeEditor = new RoutePlannerResultEditor(plannerResult);
await routeEditor.removeJobs(['job-2']);
let modifiedResult = routeEditor.getModifiedResult();
```
### Remove shipments
```ts
const routeEditor = new RoutePlannerResultEditor(plannerResult);
await routeEditor.removeShipments(['shipment-4']);
let modifiedResult = routeEditor.getModifiedResult();
```
### Add new jobs
```ts
let newJob = new Job()
.setLocation(44.50932929564537, 40.18686625)
.setPickupAmount(10)
.setId("job-5");
await routeEditor.addNewJobs('agent-A', [newJob]);
let modifiedResult = routeEditor.getModifiedResult();
```
### Add new shipments
```ts
let newShipment = new Shipment()
.setPickup(new ShipmentStep().setLocation(44.50932929564537, 40.18686625).setDuration(1000))
.setDelivery(new ShipmentStep().setLocation(44.50932929564537, 40.18686625))
.addRequirement('heavy-items')
.setId("shipment-5");
await routeEditor.addNewShipments('agent-A', [newShipment]);
let modifiedResult = routeEditor.getModifiedResult();
```
---
## Documentation
### RoutePlanner Class
| Method / Property | Description | Parameters / Types | Returns |
|------------------------------------------|-------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|--------------------------------------|
| `constructor(options, raw?)` | Creates a new `RoutePlanner` instance with provided options and optional input data. | `options: RoutePlannerOptions`<br>`raw?: RoutePlannerInputData` | `RoutePlanner` instance |
| `getRaw()` | Returns the current raw input data. | – | `RoutePlannerInputData` |
| `setRaw(value)` | Sets or replaces the raw input data. | `value: RoutePlannerInputData` | `this` |
| `setMode(mode)` | Sets the travel mode used for route optimization. | `mode: TravelMode` | `this` |
| `addAgent(agent)` | Adds an agent (e.g. vehicle, driver) to the route planner. | `agent: Agent` | `this` |
| `addJob(job)` | Adds a job (task) to be assigned to an agent. | `job: Job` | `this` |
| `addLocation(location)` | Adds a location reference. | `location: Location` | `this` |
| `addShipment(shipment)` | Adds a shipment task with pickup and delivery steps. | `shipment: Shipment` | `this` |
| `addAvoid(avoid)` | Adds an area or rule to avoid during routing. | `avoid: Avoid` | `this` |
| `setTraffic(traffic)` | Sets the traffic model used for optimization. | `traffic: TrafficType` | `this` |
| `setType(type)` | Sets the route optimization strategy (e.g., shortest, balanced). | `type: RouteType` | `this` |
| `setMaxSpeed(max_speed)` | Defines maximum allowed speed for agents. | `max_speed: number` | `this` |
| `setUnits(units)` | Sets measurement units (metric, imperial). | `units: DistanceUnitType` | `this` |
| `plan()` | Sends the route planning request and returns the optimized result. | – | `Promise<RoutePlannerResult>` |
---
### RoutePlannerResultEditor Class
| Method / Property | Description | Parameters / Types | Returns |
|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|--------------------------------------|
| `constructor(result)` | Creates a new `RoutePlannerResultEditor` instance from an existing route planner result. | `result: RoutePlannerResult` | `RoutePlannerResultEditor` instance |
| `assignJobs(agentId, jobIds)` | Assigns one or more jobs to an agent. Removes the job if it was previously assigned to another agent. | `agentId: string`<br>`jobIds: string[]` | `Promise<boolean>` |
| `assignShipments(agentId, shipmentIds)` | Assigns one or more shipments to an agent. Removes them from other agents if previously assigned. | `agentId: string`<br>`shipmentIds: string[]` | `Promise<boolean>` |
| `removeJobs(jobIds)` | Removes specified jobs from the plan. | `jobIds: string[]` | `Promise<boolean>` |
| `removeShipments(shipmentIds)` | Removes specified shipments from the plan. | `shipmentIds: string[]` | `Promise<boolean>` |
| `addNewJobs(agentId, jobs)` | Adds new jobs to an agent's schedule. | `agentId: string`<br>`jobs: Job[]` | `Promise<boolean>` |
| `addNewShipments(agentId, shipments)` | Adds new shipments to an agent's schedule. | `agentId: string`<br>`shipments: Shipment[]` | `Promise<boolean>` |
| `getModifiedResult()` | Returns the modified route planner result after editing. | – | `RoutePlannerResult` |
---
## Useful Links
- [Geoapify Route Planner API Overview](https://www.geoapify.com/route-planner-api/)
- [API Playground](https://apidocs.geoapify.com/playground/route-planner/)
- [API Documentation](https://apidocs.geoapify.com/docs/route-planner/)
---
## When to Use
The **Geoapify Route Optimization SDK** is ideal for:
- Delivery and logistics platforms
- Multi-agent job dispatching
- Shipment planning and optimization
- Interactive route editing and visualization
Simplify your logistics and delivery operations with automated and flexible route optimization.