How to Choose Between Jobs and Shipments for Route Optimization

API or service: Route Planner API
Task: Business work → jobs, shipments, or both

Examples: URL
Difficulty: Beginner
Time: 7 min

Choose between jobs and shipments for route optimization

You have work that must be assigned and ordered across one or more drivers, workers, or vehicles. Before calling the Route Planner API, decide whether each business task is an independent visit or a linked pickup-and-delivery operation.

Use a job for work performed at one location. Use a shipment when the same agent must visit a pickup and a delivery in that order. A single optimization request may contain both.

Task flow: business tasks → classify independent visits and linked orders → build jobs and shipments → optimize assignments and schedules.

Compare jobs and shipments

Requirement	Model	Reason
Visit one customer, site, or service location	`job`	The task has one location and no linked second stop
Deliver goods already loaded at the agent's start	`job` with `delivery_amount`	No pickup stop is required during the route
Collect goods and return them later	`job` with `pickup_amount`	The task adds to the agent's pickup load at one location
Pick up an order and deliver it elsewhere	`shipment`	Pickup and delivery must stay together and in the correct order
Move a passenger or parcel from A to B	`shipment`	Both stops must be assigned to the same agent
Perform a service while also transporting orders	Both	Jobs and shipments can coexist in one request

Jobs can have a location, service duration, time windows, priority, requirements, and either a pickup or delivery amount. Shipments contain separate pickup and delivery objects; each stop can have its own location, duration, and time windows. Shipment-level requirements, priority, and amount apply to the linked pair.

Do not create two unrelated jobs when pickup and delivery must remain paired. The optimizer could otherwise assign them to different agents or schedule the delivery before the pickup.

Model an independent visit

This request models a 15-minute equipment inspection at one location. The agent may perform the visit at any point in its optimized route.

POST https://api.geoapify.com/v1/routeplanner?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "mode": "drive",
  "agents": [
    {
      "id": "technician-a",
      "start_location": [13.4132, 52.5219]
    }
  ],
  "jobs": [
    {
      "id": "inspection-101",
      "location": [13.3777, 52.5163],
      "duration": 900
    }
  ]
}

Route Planner request coordinates use GeoJSON order: [longitude, latitude]. The job duration is 900 seconds, or 15 minutes. Use stable IDs so the response can be mapped back to the application's agent and task records.

Model a linked pickup and delivery

This request models one order collected at a depot and delivered to a customer. Route Planner keeps both actions on the same agent and schedules the pickup before the delivery.

POST https://api.geoapify.com/v1/routeplanner?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "mode": "drive",
  "agents": [
    {
      "id": "courier-a",
      "start_location": [13.4132, 52.5219]
    }
  ],
  "shipments": [
    {
      "id": "order-101",
      "pickup": {
        "location": [13.4132, 52.5219],
        "duration": 120
      },
      "delivery": {
        "location": [13.3777, 52.5163],
        "duration": 180
      }
    }
  ]
}

The shipment ID appears on both resulting actions, which lets the application connect the optimized pickup and delivery back to the same order. Use location_index instead of repeated coordinates when many tasks reference the same depot or facility.

Learn more