Skip to main content

PlanVehicle

One vehicle and driver. Give a start, an end, or both; without an end the route finishes at its last stop.

idstringrequired
Example: van-1
modestring

Possible values: [driving, motor_scooter, bicycle, foot, truck]

Default value: driving
start object

One end of a route — supply exactly one of hex, plus_code, gps_code, point, or profile_slug.

gps_codestring

A GhanaPostGPS digital address, with or without dashes. It is looked up in the GhanaPostGPS registry and the route uses the centre of its cell. An unknown or malformed code returns 400 VALIDATION_ERROR.

Example: GA-183-8164
plus_codestring

A full Plus Code (Open Location Code), case-insensitive. The route uses the centre of its cell (about 14 m across for a 10-digit code). Short codes are rejected as ambiguous; expand them first with GET /v2/pluscode/{code}?ref=lat,lng.

Example: 6CQXJR37+F6
location_idstring

Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.

entrance_idstring

Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.

entrance_revisioninteger

Reject if the approved revision changed.

Possible values: >= 1

profile_slugstring

Address-profile handle; access is checked before resolving coordinates/entrances

entrance_typestring

Optional explicit entrance for profile_slug. Otherwise defaults to truck/main gate selection, then profile point.

Possible values: [main, truck_gate, loading_dock, visitor, staff, pedestrian, compound]

hexstring

AfriHex code at resolution 7

Example: AF-GH-7-0GXTJJB0ZZZZZ
point object

Raw coordinate

lngnumber<double>
Example: -0.1867
latnumber<double>
Example: 5.604
headinginteger

Device compass bearing in degrees (0 = north). On dual-carriageway roads it disambiguates which carriageway the endpoint snaps to, so routes don't begin with a phantom U-turn. Omit when unknown.

Possible values: >= 0 and <= 359

Example: 270
end object

One end of a route — supply exactly one of hex, plus_code, gps_code, point, or profile_slug.

gps_codestring

A GhanaPostGPS digital address, with or without dashes. It is looked up in the GhanaPostGPS registry and the route uses the centre of its cell. An unknown or malformed code returns 400 VALIDATION_ERROR.

Example: GA-183-8164
plus_codestring

A full Plus Code (Open Location Code), case-insensitive. The route uses the centre of its cell (about 14 m across for a 10-digit code). Short codes are rejected as ambiguous; expand them first with GET /v2/pluscode/{code}?ref=lat,lng.

Example: 6CQXJR37+F6
location_idstring

Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.

entrance_idstring

Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.

entrance_revisioninteger

Reject if the approved revision changed.

Possible values: >= 1

profile_slugstring

Address-profile handle; access is checked before resolving coordinates/entrances

entrance_typestring

Optional explicit entrance for profile_slug. Otherwise defaults to truck/main gate selection, then profile point.

Possible values: [main, truck_gate, loading_dock, visitor, staff, pedestrian, compound]

hexstring

AfriHex code at resolution 7

Example: AF-GH-7-0GXTJJB0ZZZZZ
point object

Raw coordinate

lngnumber<double>
Example: -0.1867
latnumber<double>
Example: 5.604
headinginteger

Device compass bearing in degrees (0 = north). On dual-carriageway roads it disambiguates which carriageway the endpoint snaps to, so routes don't begin with a phantom U-turn. Omit when unknown.

Possible values: >= 0 and <= 359

Example: 270
capacityinteger[]

What the vehicle can carry, in one or more units (for example [20] parcels, or [20, 500] parcels and kilograms). Every capacity and amount in a plan must have the same number of values.

Possible values: >= 0

Example: [20]
skillsstring[]

A job or shipment that lists skills can only go to a vehicle that has all of them.

Example: ["cold_chain"]
shift object
startstring<date-time>required
endstring<date-time>required
breaks object[]
  • Array [
  • window objectrequired
    startstring<date-time>required
    endstring<date-time>required
    duration_sintegerrequired

    Possible values: >= 1

  • ]
  • max_stopsinteger

    Most jobs, pickups and deliveries this vehicle may take, across all its trips.

    Possible values: >= 0

    max_tripsinteger

    How many times this vehicle may go out (default 1). Each trip starts and ends at start, and capacity applies per trip, so an okada carrying 5 parcels can deliver 15 in 3 trips. Each trip is planned from when the vehicle is back, so time windows hold. end, if given, must be the same place as start.

    Possible values: >= 1 and <= 6

    reload_sinteger

    Seconds at base between trips (default 600). Needs max_trips above 1.

    Possible values: >= 0 and <= 14400

    cost object

    Relative costs used to choose between vehicles. Use the same units across the fleet.

    fixedinteger

    Cost of using this vehicle at all.

    per_hourinteger

    Cost per hour of travel (default 3600).

    per_kminteger

    Cost per kilometre.

    PlanVehicle
    {
    "id": "van-1",
    "mode": "driving",
    "start": {
    "gps_code": "GA-183-8164",
    "plus_code": "6CQXJR37+F6",
    "location_id": "string",
    "entrance_id": "string",
    "entrance_revision": 0,
    "profile_slug": "string",
    "entrance_type": "main",
    "hex": "AF-GH-7-0GXTJJB0ZZZZZ",
    "point": {
    "lng": -0.1867,
    "lat": 5.604
    },
    "heading": 270
    },
    "end": {
    "gps_code": "GA-183-8164",
    "plus_code": "6CQXJR37+F6",
    "location_id": "string",
    "entrance_id": "string",
    "entrance_revision": 0,
    "profile_slug": "string",
    "entrance_type": "main",
    "hex": "AF-GH-7-0GXTJJB0ZZZZZ",
    "point": {
    "lng": -0.1867,
    "lat": 5.604
    },
    "heading": 270
    },
    "capacity": [
    20
    ],
    "skills": [
    "cold_chain"
    ],
    "shift": {
    "start": "2024-07-29T15:51:28.071Z",
    "end": "2024-07-29T15:51:28.071Z"
    },
    "breaks": [
    {
    "window": {
    "start": "2024-07-29T15:51:28.071Z",
    "end": "2024-07-29T15:51:28.071Z"
    },
    "duration_s": 0
    }
    ],
    "max_stops": 0,
    "max_trips": 0,
    "reload_s": 0,
    "cost": {
    "fixed": 0,
    "per_hour": 0,
    "per_km": 0
    }
    }