Skip to main content

RoutePlanRequest

start_atstring<date-time>

The plan's clock origin (default: now). No time window may start before it. It also sets the traffic period for travel times.

vehicles object[]required

Possible values: >= 1, <= 20

  • Array [
  • 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.

  • ]
  • jobs object[]
  • Array [
  • idstringrequired
    Example: order-1001
    location objectrequired

    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
    service_sinteger

    Time spent at the stop.

    Possible values: >= 0

    deliveryinteger[]

    Load dropped here, carried from the vehicle's start.

    Possible values: >= 0

    pickupinteger[]

    Load collected here, carried to the vehicle's end.

    Possible values: >= 0

    skillsstring[]
    priorityinteger

    When not everything fits, higher-priority stops are kept first.

    Possible values: >= 0 and <= 100

    time_windows object[]

    When the vehicle may arrive. It waits if early.

  • Array [
  • startstring<date-time>required
    endstring<date-time>required
  • ]
  • ]
  • shipments object[]
  • Array [
  • idstringrequired
    Example: parcel-77
    amountinteger[]

    Possible values: >= 0

    skillsstring[]
    priorityinteger

    Possible values: >= 0 and <= 100

    pickup objectrequired
    location objectrequired

    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
    service_sinteger

    Possible values: >= 0

    time_windows object[]
  • Array [
  • startstring<date-time>required
    endstring<date-time>required
  • ]
  • delivery objectrequired
    location objectrequired

    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
    service_sinteger

    Possible values: >= 0

    time_windows object[]
  • Array [
  • startstring<date-time>required
    endstring<date-time>required
  • ]
  • ]
  • options object
    trafficboolean

    Scale travel times by the Ghana traffic model for the period at start_at.

    Default value: true
    RoutePlanRequest
    {
    "start_at": "2024-07-29T15:51:28.071Z",
    "vehicles": [
    {
    "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
    }
    }
    ],
    "jobs": [
    {
    "id": "order-1001",
    "location": {
    "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
    },
    "service_s": 0,
    "delivery": [
    0
    ],
    "pickup": [
    0
    ],
    "skills": [
    "string"
    ],
    "priority": 0,
    "time_windows": [
    {
    "start": "2024-07-29T15:51:28.071Z",
    "end": "2024-07-29T15:51:28.071Z"
    }
    ]
    }
    ],
    "shipments": [
    {
    "id": "parcel-77",
    "amount": [
    0
    ],
    "skills": [
    "string"
    ],
    "priority": 0,
    "pickup": {
    "location": {
    "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
    },
    "service_s": 0,
    "time_windows": [
    {
    "start": "2024-07-29T15:51:28.071Z",
    "end": "2024-07-29T15:51:28.071Z"
    }
    ]
    },
    "delivery": {
    "location": {
    "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
    },
    "service_s": 0,
    "time_windows": [
    {
    "start": "2024-07-29T15:51:28.071Z",
    "end": "2024-07-29T15:51:28.071Z"
    }
    ]
    }
    }
    ],
    "options": {
    "traffic": true
    }
    }