Routes

Routes for every way of travelling, the route matrix and route optimisation.

On this page

A route, with up to 25 intermediates
Travel times from many origins to many destinations (per element)
Which vehicle visits which stops, in what order

Note:

Send your key as key=YOUR_API_KEY on the address, or in the X-NWays-Api-Key header. API keys

Base address: https://nways.ng/maps/v1

A route, with up to 25 intermediates

POST https://nways.ng/maps/v1/routes/compute

Drive, van, okada (motorbike taxi; keeps to okada bans, walks past a ban area's edge), motorbike (your own) and dispatch (couriers' bikes: exempt from passenger-okada bans), keke and danfo (keep to their bans), walk, bicycle, boat (passenger boats and jetties) and train. Postcodes route to the building's best entrance; where the road stops short of the door the route says where to stop and how to finish (lastMile); tolls in their currencies, border crossings, gated estates, bans avoided with their sources. fields= picks fields of each route. Reasons: MODE_INVALID, LANG_INVALID, ROUTING_PREFERENCE_INVALID, TOO_MANY_INTERMEDIATES, INTERMEDIATES_NOT_SUPPORTED, AVOID_INVALID, TOLL_VEHICLE_INVALID, LAST_MILE_INVALID, ACCESS_INVALID, WAYPOINT_INVALID, POSTCODE_INVALID, POSTCODE_NOT_FOUND, GHANAPOST_INVALID, GHANAPOST_NOT_FOUND, PLUSCODE_INVALID, NO_ROUTE, NO_ROAD_ROUTE, ROUTE_TOO_FAR, ROUTING_UNAVAILABLE, OKADA_BANNED_ORIGIN, OKADA_BANNED_DESTINATION, OKADA_BANNED_ROUTE, KEKE_BANNED_*, DANFO_BANNED_*, MOTORBIKE_BANNED_*, ROUTING_UNAVAILABLE (503).

Parameters

Name	In	Type	Description
`fields`	query	`string`	Comma list of the fields to keep in each result (`a.b` reaches into objects; `id` is always kept; `*` = all).

Request body

Field	Type	Description
`origin`	`Waypoint`	Required. Exactly one of lat and lng, postcode (NIPOST: routes to its best entrance), ghanaPost, or plusCode (full, or short with a town after it).
`origin.lat`	`number`
`origin.lng`	`number`
`origin.postcode`	`string`
`origin.ghanaPost`	`string`
`origin.plusCode`	`string`
`origin.heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`destination`	`Waypoint`	Required. Exactly one of lat and lng, postcode (NIPOST: routes to its best entrance), ghanaPost, or plusCode (full, or short with a town after it).
`destination.lat`	`number`
`destination.lng`	`number`
`destination.postcode`	`string`
`destination.ghanaPost`	`string`
`destination.plusCode`	`string`
`destination.heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`intermediates`	`Waypoint[]`	At most 25 items.
`intermediates[].lat`	`number`
`intermediates[].lng`	`number`
`intermediates[].postcode`	`string`
`intermediates[].ghanaPost`	`string`
`intermediates[].plusCode`	`string`
`intermediates[].heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`mode`	`string`	One of: `drive`, `van`, `okada`, `motorbike`, `dispatch`, `keke`, `danfo`, `walk`, `bicycle`, `boat`, `train`. Default: `drive`.
`alternatives`	`boolean`	Up to 2 more routes (no intermediates). Default: `false`.
`routingPreference`	`string`	One of: `traffic_unaware`, `traffic_aware`. Default: `traffic_unaware`.
`departAt`	`string (date-time)`
`avoid`	`string[]`
`lang`	`string`	One of: `en`, `fr`, `pt`.
`tollVehicle`	`string`	Toll tariff class (van: bus). One of: `car`, `suv`, `bus`, `truck`.
`access`	`string`	Train and boat trips: to and from stations and jetties. One of: `walk`, `okada`, `drive`.
`lastMile`	`string`	One of: `walk`, `okada`.
`allowBans`	`string[]`	Unconfirmed ban ids (from unconfirmedBans) to route through anyway.
`fares`	`boolean`	Add fare estimates to each route (advanced SKU). Default: `false`.

cURL

curl -X POST "https://nways.ng/maps/v1/routes/compute" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":{"lat":6.4474,"lng":3.472},"destination":{"postcode":"LA08A09DB10"},"mode":"drive","routingPreference":"traffic_aware"}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/routes/compute', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "origin": {
      "lat": 6.4474,
      "lng": 3.472
    },
    "destination": {
      "postcode": "LA08A09DB10"
    },
    "mode": "drive",
    "routingPreference": "traffic_aware"
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/routes/compute",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"origin": {"lat": 6.4474, "lng": 3.472}, "destination": {"postcode": "LA08A09DB10"}, "mode": "drive", "routingPreference": "traffic_aware"},
    timeout=10,
)
data = res.json()

Response

Routes

Field	Type	Description
`routes`	`Route[]`	Required.
`routes[].distanceM`	`number`	Required.
`routes[].durationS`	`number`	Required.
`routes[].staticDurationS`	`number`	Required. Without live traffic
`routes[].trafficDelayS`	`number`	Required. What traffic and incidents add now (traffic_aware).
`routes[].speedSource`	`string`	One of: `live`, `typical`, `estimated`.
`routes[].summary`	`string`
`routes[].geometry`	`LineString`	Required.
`routes[].geometry.type`	`string`	Required.
`routes[].geometry.coordinates`	`number[][]`	Required.
`routes[].legs`	`Leg[]`	Required. One per part between stops.
`routes[].legs[].distanceM`	`number`	Required.
`routes[].legs[].durationS`	`number`	Required.
`routes[].steps`	`Step[]`	Required.
`routes[].steps[].maneuver`	`string`	Required. depart, arrive, continue, left, right, slight_left, sharp_right, uturn_left, roundabout_enter, ferry_enter, … (other)
`routes[].steps[].instruction`	`string`	Required.
`routes[].steps[].distanceM`	`number`	Required.
`routes[].steps[].durationS`	`number`	Required.
`routes[].steps[].streetNames`	`string[]`
`routes[].steps[].startIndex`	`integer`	Required. Index into geometry.coordinates
`routes[].steps[].endIndex`	`integer`	Required.
`routes[].steps[].roundaboutExit`	`integer`
`routes[].steps[].toward`	`string[]`
`routes[].steps[].atTrafficLight`	`boolean`
`routes[].steps[].crossing`	`string`	On foot: footbridge, underpass, zebra, signals, crossing, junction
`routes[].segments`	`object[]`	Trips that change how you travel (train, boat, okada with a walk past a ban).
`routes[].segments[].mode`	`string`	Required. One of: `walk`, `okada`, `drive`, `train`, `boat`.
`routes[].segments[].line`	`string`
`routes[].segments[].from`	`string`	Required.
`routes[].segments[].to`	`string`	Required.
`routes[].segments[].distanceM`	`number`	Required.
`routes[].segments[].durationS`	`number`	Required.
`routes[].segments[].waitS`	`number`
`routes[].segments[].stops`	`integer`
`routes[].segments[].scheduled`	`boolean`
`routes[].segments[].estimated`	`boolean`
`routes[].segments[].fare`	`string`
`routes[].segments[].note`	`string`
`routes[].segments[].geometry`	`LineString`	Required.
`routes[].segments[].geometry.type`	`string`	Required.
`routes[].segments[].geometry.coordinates`	`number[][]`	Required.
`routes[].congestion`	`object[]`
`routes[].congestion[].startIndex`	`integer`
`routes[].congestion[].endIndex`	`integer`
`routes[].congestion[].level`	`string`
`routes[].tolls`	`object`
`routes[].tolls.gates`	`object[]`
`routes[].tolls.gates[].name`	`string`
`routes[].tolls.gates[].location`	`Point`
`routes[].tolls.gates[].atM`	`integer`
`routes[].tolls.gates[].price`	`integer \| null`
`routes[].tolls.gates[].currency`	`string`
`routes[].tolls.gates[].payment`	`string`
`routes[].tolls.total`	`object`
`routes[].tolls.unknownPrices`	`integer`
`routes[].borderCrossings`	`object[]`
`routes[].borderCrossings[].from`	`string`
`routes[].borderCrossings[].to`	`string`
`routes[].borderCrossings[].location`	`Point`
`routes[].borderCrossings[].location.type`	`string`	Required.
`routes[].borderCrossings[].location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`routes[].borderCrossings[].atM`	`integer`
`routes[].borderCrossings[].post`	`string`
`routes[].borderCrossings[].clockChangeH`	`number`
`routes[].vehicleRules`	`object`	okada, keke and danfo trips
`routes[].vehicleRules.vehicle`	`string`	One of: `okada`, `motorbike`, `keke`, `danfo`.
`routes[].vehicleRules.avoided`	`Ban[]`
`routes[].vehicleRules.avoided[].id`	`string`	Required.
`routes[].vehicleRules.avoided[].zone`	`string`	Required.
`routes[].vehicleRules.avoided[].scope`	`string`	Required.
`routes[].vehicleRules.avoided[].hours`	`string`
`routes[].vehicleRules.avoided[].since`	`string`
`routes[].vehicleRules.avoided[].source`	`string (uri)`
`routes[].vehicleRules.avoided[].where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`routes[].vehicleRules.avoided[].walkM`	`number`
`routes[].vehicleRules.advice`	`Ban[]`
`routes[].vehicleRules.advice[].id`	`string`	Required.
`routes[].vehicleRules.advice[].zone`	`string`	Required.
`routes[].vehicleRules.advice[].scope`	`string`	Required.
`routes[].vehicleRules.advice[].hours`	`string`
`routes[].vehicleRules.advice[].since`	`string`
`routes[].vehicleRules.advice[].source`	`string (uri)`
`routes[].vehicleRules.advice[].where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`routes[].vehicleRules.advice[].walkM`	`number`
`routes[].vehicleRules.endBan`	`Ban`
`routes[].vehicleRules.endBan.id`	`string`	Required.
`routes[].vehicleRules.endBan.zone`	`string`	Required.
`routes[].vehicleRules.endBan.scope`	`string`	Required.
`routes[].vehicleRules.endBan.hours`	`string`
`routes[].vehicleRules.endBan.since`	`string`
`routes[].vehicleRules.endBan.source`	`string (uri)`
`routes[].vehicleRules.endBan.where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`routes[].vehicleRules.endBan.walkM`	`number`
`routes[].vehicleRules.allowedByRequest`	`Ban[]`
`routes[].vehicleRules.allowedByRequest[].id`	`string`	Required.
`routes[].vehicleRules.allowedByRequest[].zone`	`string`	Required.
`routes[].vehicleRules.allowedByRequest[].scope`	`string`	Required.
`routes[].vehicleRules.allowedByRequest[].hours`	`string`
`routes[].vehicleRules.allowedByRequest[].since`	`string`
`routes[].vehicleRules.allowedByRequest[].source`	`string (uri)`
`routes[].vehicleRules.allowedByRequest[].where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`routes[].vehicleRules.allowedByRequest[].walkM`	`number`
`routes[].vehicleRules.reported`	`object[]`
`routes[].vehicleRules.reported[].location`	`Point`
`routes[].vehicleRules.reported[].reporters`	`integer`
`routes[].vehicleRules.reported[].lastSeen`	`string`
`routes[].lastMile`	`object`
`routes[].lastMile.stopAt`	`Point`
`routes[].lastMile.stopAt.type`	`string`	Required.
`routes[].lastMile.stopAt.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`routes[].lastMile.stopName`	`string`
`routes[].lastMile.mode`	`string`
`routes[].lastMile.distanceM`	`number`
`routes[].lastMile.durationS`	`number`
`routes[].lastMile.geometry`	`LineString`
`routes[].lastMile.geometry.type`	`string`	Required.
`routes[].lastMile.geometry.coordinates`	`number[][]`	Required.
`routes[].access`	`object`
`routes[].access.kind`	`string`	One of: `estate`, `government`, `military`, `police`, `gate`.
`routes[].access.text`	`string`
`routes[].access.name`	`string`
`routes[].access.gate`	`Point`
`routes[].access.gate.type`	`string`	Required.
`routes[].access.gate.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`routes[].access.dropOffAtGate`	`boolean`
`routes[].roadCondition`	`object`
`routes[].roadCondition.roughM`	`number`
`routes[].country`	`string`
`routes[].warnings`	`string[]`
`routes[].fares`	`FareEstimate[]`
`routes[].fares[].mode`	`string`	Required. One of: `taxi`, `shared_taxi`, `okada`, `keke`, `bus`, `ridehail`, `boat`.
`routes[].fares[].service`	`string`
`routes[].fares[].currency`	`string`	Required. One of: `NGN`, `GHS`, `XOF`.
`routes[].fares[].low`	`integer`	Required.
`routes[].fares[].typical`	`integer`	Required.
`routes[].fares[].high`	`integer`	Required.
`routes[].fares[].text`	`string`	Required.
`routes[].fares[].perPerson`	`boolean`	Required.
`routes[].fares[].charter`	`boolean`	Required.
`routes[].fares[].night`	`boolean`
`routes[].fares[].rush`	`boolean`
`routes[].fares[].rain`	`boolean`
`routes[].fares[].basis`	`string`	Required. One of: `crowd`, `guide`.
`routes[].fares[].reports`	`integer`	Required.
`routes[].fares[].durationS`	`number`	Required.
`routes[].fares[].openingOffer`	`integer`	Where prices are haggled: a good first offer.
`routes[].fares[].sources`	`string (uri)[]`
`waypoints`	`object[]`	Required. Where each waypoint was routed to, in order.
`waypoints[].location`	`Point`	Required.
`waypoints[].location.type`	`string`	Required.
`waypoints[].location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`waypoints[].postcode`	`string`
`waypoints[].entrance`	`string`
`mode`	`string`	Required. One of: `drive`, `van`, `okada`, `motorbike`, `dispatch`, `keke`, `danfo`, `walk`, `bicycle`, `boat`, `train`. Default: `drive`.
`warnings`	`string[]`
`unconfirmedBans`	`Ban[]`
`unconfirmedBans[].id`	`string`	Required.
`unconfirmedBans[].zone`	`string`	Required.
`unconfirmedBans[].scope`	`string`	Required.
`unconfirmedBans[].hours`	`string`
`unconfirmedBans[].since`	`string`
`unconfirmedBans[].source`	`string (uri)`
`unconfirmedBans[].where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`unconfirmedBans[].walkM`	`number`
`attribution`	`string`	Required.

200 OK

{
  "routes": [
    {
      "distanceM": 0,
      "durationS": 0,
      "staticDurationS": 0,
      "trafficDelayS": 0,
      "speedSource": "live",
      "summary": "Admiralty Way and Awudu Ekpekha Boulevard",
      "geometry": {
        "type": "string",
        "coordinates": [
          []
        ]
      },
      "legs": [
        {
          "distanceM": 0,
          "durationS": 0
        }
      ],
      "steps": [
        {
          "maneuver": "right",
          "instruction": "Turn right onto Admiralty Way.",
          "distanceM": 0,
          "durationS": 0,
          "streetNames": [],
          "startIndex": 0,
          "endIndex": 0,
          "roundaboutExit": 0,
          "toward": [],
          "atTrafficLight": true,
          "crossing": "string"
        }
      ],
      "segments": [
        {
          "mode": "walk",
          "line": "string",
          "from": "string",
          "to": "string",
          "distanceM": 0,
          "durationS": 0,
          "waitS": 0,
          "stops": 0,
          "scheduled": true,
          "estimated": true,
          "fare": "string",
          "note": "string",
          "geometry": {}
        }
      ],
      "congestion": [
        {
          "startIndex": 0,
          "endIndex": 0,
          "level": "string"
        }
      ],
      "tolls": {
        "gates": [
          {}
        ],
        "total": {
          "NGN": 300
        },
        "unknownPrices": 0
      },
      "borderCrossings": [
        {
          "from": "string",
          "to": "string",
          "location": {},
          "atM": 0,
          "post": "string",
          "clockChangeH": 0
        }
      ],
      "vehicleRules": {
        "vehicle": "okada",
        "avoided": [
          {}
        ],
        "advice": [
          {}
        ],
        "endBan": {
          "id": "string",
          "zone": "Third Mainland Bridge",
          "scope": "string",
          "hours": "string",
          "since": "string",
          "source": "string",
          "where": "origin",
          "walkM": 0
        },
        "allowedByRequest": [
          {}
        ],
        "reported": [
          {}
        ]
      },
      "lastMile": {
        "stopAt": {
          "type": "string",
          "coordinates": []
        },
        "stopName": "string",
        "mode": "string",
        "distanceM": 0,
        "durationS": 0,
        "geometry": {
          "type": "string",
          "coordinates": []
        }
      },
      "access": {
        "kind": "estate",
        "text": "string",
        "name": "string",
        "gate": {
          "type": "string",
          "coordinates": []
        },
        "dropOffAtGate": true
      },
      "roadCondition": {
        "roughM": 0
      },
      "country": "string",
      "warnings": [
        "string"
      ],
      "fares": [
        {
          "mode": "taxi",
          "service": "Bolt",
          "currency": "NGN",
          "low": 0,
          "typical": 0,
          "high": 0,
          "text": "₦3,000–4,500",
          "perPerson": true,
          "charter": true,
          "night": true,
          "rush": true,
          "rain": true,
          "basis": "crowd",
          "reports": 0,
          "durationS": 0,
          "openingOffer": 0,
          "sources": []
        }
      ]
    }
  ],
  "waypoints": [
    {
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "postcode": "string",
      "entrance": "string"
    }
  ],
  "mode": "drive",
  "warnings": [
    "string"
  ],
  "unconfirmedBans": [
    {
      "id": "string",
      "zone": "Third Mainland Bridge",
      "scope": "string",
      "hours": "string",
      "since": "string",
      "source": "string",
      "where": "origin",
      "walkM": 0
    }
  ],
  "attribution": "string"
}

Errors

default Error

Travel times from many origins to many destinations (per element)

POST https://nways.ng/maps/v1/routes/matrix

Up to 50 origins and 50 destinations, 625 elements (origins × destinations), each billed as one route_matrix unit. Modes drive, van, walk, bicycle; okada, keke and danfo keep to their bans as /routes/compute does (an element from or to a ban area is NOT_ALLOWED, with the ban); motorbike and dispatch to bans on every motorcycle only. Points at most 400 km apart by car, 200 km otherwise. Reasons: MODE_INVALID, MATRIX_TOO_LARGE, MATRIX_TOO_FAR, WAYPOINT_INVALID, POSTCODE_INVALID, POSTCODE_NOT_FOUND, GHANAPOST_INVALID, GHANAPOST_NOT_FOUND, PLUSCODE_INVALID, ROUTING_UNAVAILABLE (503).

Parameters

Name	In	Type	Description
`fields`	query	`string`	Comma list of the fields to keep in each result (`a.b` reaches into objects; `id` is always kept; `*` = all).

Request body

Field	Type	Description
`origins`	`Waypoint[]`	Required. At least 1 items, at most 50 items.
`origins[].lat`	`number`
`origins[].lng`	`number`
`origins[].postcode`	`string`
`origins[].ghanaPost`	`string`
`origins[].plusCode`	`string`
`origins[].heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`destinations`	`Waypoint[]`	Required. At least 1 items, at most 50 items.
`destinations[].lat`	`number`
`destinations[].lng`	`number`
`destinations[].postcode`	`string`
`destinations[].ghanaPost`	`string`
`destinations[].plusCode`	`string`
`destinations[].heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`mode`	`string`	okada, keke and danfo keep to their bans (as /routes/compute); motorbike and dispatch (couriers' bikes) only to bans on every motorcycle. One of: `drive`, `van`, `okada`, `motorbike`, `dispatch`, `keke`, `danfo`, `walk`, `bicycle`. Default: `drive`.
`allowBans`	`string[]`

cURL

curl -X POST "https://nways.ng/maps/v1/routes/matrix" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origins":[{"lat":6.4474,"lng":3.472},{"postcode":"LA08A09DB09"}],"destinations":[{"lat":6.43,"lng":3.42},{"lat":6.45,"lng":3.4}],"mode":"motorbike"}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/routes/matrix', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "origins": [
      {
        "lat": 6.4474,
        "lng": 3.472
      },
      {
        "postcode": "LA08A09DB09"
      }
    ],
    "destinations": [
      {
        "lat": 6.43,
        "lng": 3.42
      },
      {
        "lat": 6.45,
        "lng": 3.4
      }
    ],
    "mode": "motorbike"
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/routes/matrix",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"origins": [{"lat": 6.4474, "lng": 3.472}, {"postcode": "LA08A09DB09"}], "destinations": [{"lat": 6.43, "lng": 3.42}, {"lat": 6.45, "lng": 3.4}], "mode": "motorbike"},
    timeout=10,
)
data = res.json()

Response

The matrix

Field	Type	Description
`elements`	`object[]`	Required.
`elements[].originIndex`	`integer`	Required.
`elements[].destinationIndex`	`integer`	Required.
`elements[].status`	`string`	Required. NOT_ALLOWED: the origin or destination is inside a ban area for the mode (ban says which). One of: `OK`, `ROUTE_NOT_FOUND`, `NOT_ALLOWED`.
`elements[].durationS`	`number`	Required.
`elements[].distanceM`	`number`	Required.
`elements[].ban`	`Ban`
`elements[].ban.id`	`string`	Required.
`elements[].ban.zone`	`string`	Required.
`elements[].ban.scope`	`string`	Required.
`elements[].ban.hours`	`string`
`elements[].ban.since`	`string`
`elements[].ban.source`	`string (uri)`
`elements[].ban.where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`elements[].ban.walkM`	`number`
`origins`	`Point[]`	Required.
`origins[].type`	`string`	Required.
`origins[].coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`destinations`	`Point[]`	Required.
`destinations[].type`	`string`	Required.
`destinations[].coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`mode`	`string`	Required.
`attribution`	`string`	Required.

200 OK

{
  "elements": [
    {
      "originIndex": 0,
      "destinationIndex": 0,
      "status": "OK",
      "durationS": 0,
      "distanceM": 0,
      "ban": {
        "id": "string",
        "zone": "Third Mainland Bridge",
        "scope": "string",
        "hours": "string",
        "since": "string",
        "source": "string",
        "where": "origin",
        "walkM": 0
      }
    }
  ],
  "origins": [
    {
      "type": "string",
      "coordinates": [
        0
      ]
    }
  ],
  "destinations": [
    {
      "type": "string",
      "coordinates": [
        0
      ]
    }
  ],
  "mode": "string",
  "attribution": "string"
}

Errors

default Error

Which vehicle visits which stops, in what order

POST https://nways.ng/maps/v1/routes/optimize

Modes as /routes/matrix: stops inside a ban area for the mode are unassigned and listed in notAllowed. Up to 50 stops and 5 vehicles (start, optional end, capacity): the least total time within each vehicle's capacity, by a fast heuristic on the engine's travel times (not a guaranteed optimum). Each vehicle's route is planned like /routes/compute unless geometry is false. One route_optimization call. Reasons: MODE_INVALID, STOPS_INVALID, VEHICLES_INVALID, STOP_ID_INVALID, VEHICLE_ID_INVALID, STOP_INVALID, CAPACITY_INVALID, STOPS_TOO_FAR, WAYPOINT_INVALID, POSTCODE_INVALID, POSTCODE_NOT_FOUND, GHANAPOST_INVALID, GHANAPOST_NOT_FOUND, PLUSCODE_INVALID, LANG_INVALID, ROUTING_UNAVAILABLE (503).

Request body

Field	Type	Description
`stops`	`object[]`	Required. At least 1 items, at most 50 items.
`stops[].id`	`string`	Required.
`stops[].location`	`Waypoint`	Required. Exactly one of lat and lng, postcode (NIPOST: routes to its best entrance), ghanaPost, or plusCode (full, or short with a town after it).
`stops[].location.lat`	`number`
`stops[].location.lng`	`number`
`stops[].location.postcode`	`string`
`stops[].location.ghanaPost`	`string`
`stops[].location.plusCode`	`string`
`stops[].location.heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`stops[].demand`	`integer`	Default: `1`. ≥ 1.
`stops[].serviceS`	`number`	Default: `0`. ≥ 0, ≤ 14400.
`vehicles`	`object[]`	Required. At least 1 items, at most 5 items.
`vehicles[].id`	`string`	Required.
`vehicles[].start`	`Waypoint`	Required. Exactly one of lat and lng, postcode (NIPOST: routes to its best entrance), ghanaPost, or plusCode (full, or short with a town after it).
`vehicles[].start.lat`	`number`
`vehicles[].start.lng`	`number`
`vehicles[].start.postcode`	`string`
`vehicles[].start.ghanaPost`	`string`
`vehicles[].start.plusCode`	`string`
`vehicles[].start.heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`vehicles[].end`	`Waypoint`	Exactly one of lat and lng, postcode (NIPOST: routes to its best entrance), ghanaPost, or plusCode (full, or short with a town after it).
`vehicles[].end.lat`	`number`
`vehicles[].end.lng`	`number`
`vehicles[].end.postcode`	`string`
`vehicles[].end.ghanaPost`	`string`
`vehicles[].end.plusCode`	`string`
`vehicles[].end.heading`	`number`	Origin only: direction of travel (degrees), so a moving vehicle doesn't start with a U-turn.
`vehicles[].capacity`	`integer`	0 = no limit Default: `0`. ≥ 0.
`mode`	`string`	okada, keke and danfo keep to their bans (as /routes/compute); motorbike and dispatch (couriers' bikes) only to bans on every motorcycle. One of: `drive`, `van`, `okada`, `motorbike`, `dispatch`, `keke`, `danfo`, `walk`, `bicycle`. Default: `drive`.
`allowBans`	`string[]`
`geometry`	`boolean`	Default: `true`.
`lang`	`string`	One of: `en`, `fr`, `pt`.

cURL

curl -X POST "https://nways.ng/maps/v1/routes/optimize" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stops":[{"id":"order-1","location":{"lat":6.44,"lng":3.4},"serviceS":120},{"id":"order-2","location":{"postcode":"LA08A09DB09"},"demand":2}],"vehicles":[{"id":"bike-1","start":{"lat":6.4474,"lng":3.472},"capacity":6}],"mode":"motorbike"}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/routes/optimize', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "stops": [
      {
        "id": "order-1",
        "location": {
          "lat": 6.44,
          "lng": 3.4
        },
        "serviceS": 120
      },
      {
        "id": "order-2",
        "location": {
          "postcode": "LA08A09DB09"
        },
        "demand": 2
      }
    ],
    "vehicles": [
      {
        "id": "bike-1",
        "start": {
          "lat": 6.4474,
          "lng": 3.472
        },
        "capacity": 6
      }
    ],
    "mode": "motorbike"
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/routes/optimize",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"stops": [{"id": "order-1", "location": {"lat": 6.44, "lng": 3.4}, "serviceS": 120}, {"id": "order-2", "location": {"postcode": "LA08A09DB09"}, "demand": 2}], "vehicles": [{"id": "bike-1", "start": {"lat": 6.4474, "lng": 3.472}, "capacity": 6}], "mode": "motorbike"},
    timeout=10,
)
data = res.json()

Response

The plan

Field	Type	Description
`routes`	`object[]`	Required.
`routes[].vehicle`	`string`	Required.
`routes[].stops`	`string[]`	Required. Stop ids in visiting order
`routes[].durationS`	`number`	Required.
`routes[].distanceM`	`number`	Required.
`routes[].serviceS`	`number`	Required.
`routes[].load`	`integer`	Required.
`routes[].arrivalsS`	`number[]`	Required. Seconds from the start to each stop
`routes[].route`	`Route`
`routes[].route.distanceM`	`number`	Required.
`routes[].route.durationS`	`number`	Required.
`routes[].route.staticDurationS`	`number`	Required. Without live traffic
`routes[].route.trafficDelayS`	`number`	Required. What traffic and incidents add now (traffic_aware).
`routes[].route.speedSource`	`string`	One of: `live`, `typical`, `estimated`.
`routes[].route.summary`	`string`
`routes[].route.geometry`	`LineString`	Required.
`routes[].route.geometry.type`	`string`	Required.
`routes[].route.geometry.coordinates`	`number[][]`	Required.
`routes[].route.legs`	`Leg[]`	Required. One per part between stops.
`routes[].route.legs[].distanceM`	`number`	Required.
`routes[].route.legs[].durationS`	`number`	Required.
`routes[].route.steps`	`Step[]`	Required.
`routes[].route.steps[].maneuver`	`string`	Required. depart, arrive, continue, left, right, slight_left, sharp_right, uturn_left, roundabout_enter, ferry_enter, … (other)
`routes[].route.steps[].instruction`	`string`	Required.
`routes[].route.steps[].distanceM`	`number`	Required.
`routes[].route.steps[].durationS`	`number`	Required.
`routes[].route.steps[].streetNames`	`string[]`
`routes[].route.steps[].startIndex`	`integer`	Required. Index into geometry.coordinates
`routes[].route.steps[].endIndex`	`integer`	Required.
`routes[].route.steps[].roundaboutExit`	`integer`
`routes[].route.steps[].toward`	`string[]`
`routes[].route.steps[].atTrafficLight`	`boolean`
`routes[].route.steps[].crossing`	`string`	On foot: footbridge, underpass, zebra, signals, crossing, junction
`routes[].route.segments`	`object[]`	Trips that change how you travel (train, boat, okada with a walk past a ban).
`routes[].route.segments[].mode`	`string`	Required. One of: `walk`, `okada`, `drive`, `train`, `boat`.
`routes[].route.segments[].line`	`string`
`routes[].route.segments[].from`	`string`	Required.
`routes[].route.segments[].to`	`string`	Required.
`routes[].route.segments[].distanceM`	`number`	Required.
`routes[].route.segments[].durationS`	`number`	Required.
`routes[].route.segments[].waitS`	`number`
`routes[].route.segments[].stops`	`integer`
`routes[].route.segments[].scheduled`	`boolean`
`routes[].route.segments[].estimated`	`boolean`
`routes[].route.segments[].fare`	`string`
`routes[].route.segments[].note`	`string`
`routes[].route.segments[].geometry`	`LineString`	Required.
`routes[].route.congestion`	`object[]`
`routes[].route.congestion[].startIndex`	`integer`
`routes[].route.congestion[].endIndex`	`integer`
`routes[].route.congestion[].level`	`string`
`routes[].route.tolls`	`object`
`routes[].route.tolls.gates`	`object[]`
`routes[].route.tolls.total`	`object`
`routes[].route.tolls.unknownPrices`	`integer`
`routes[].route.borderCrossings`	`object[]`
`routes[].route.borderCrossings[].from`	`string`
`routes[].route.borderCrossings[].to`	`string`
`routes[].route.borderCrossings[].location`	`Point`
`routes[].route.borderCrossings[].atM`	`integer`
`routes[].route.borderCrossings[].post`	`string`
`routes[].route.borderCrossings[].clockChangeH`	`number`
`routes[].route.vehicleRules`	`object`	okada, keke and danfo trips
`routes[].route.vehicleRules.vehicle`	`string`	One of: `okada`, `motorbike`, `keke`, `danfo`.
`routes[].route.vehicleRules.avoided`	`Ban[]`
`routes[].route.vehicleRules.advice`	`Ban[]`
`routes[].route.vehicleRules.endBan`	`Ban`
`routes[].route.vehicleRules.allowedByRequest`	`Ban[]`
`routes[].route.vehicleRules.reported`	`object[]`
`routes[].route.lastMile`	`object`
`routes[].route.lastMile.stopAt`	`Point`
`routes[].route.lastMile.stopName`	`string`
`routes[].route.lastMile.mode`	`string`
`routes[].route.lastMile.distanceM`	`number`
`routes[].route.lastMile.durationS`	`number`
`routes[].route.lastMile.geometry`	`LineString`
`routes[].route.access`	`object`
`routes[].route.access.kind`	`string`	One of: `estate`, `government`, `military`, `police`, `gate`.
`routes[].route.access.text`	`string`
`routes[].route.access.name`	`string`
`routes[].route.access.gate`	`Point`
`routes[].route.access.dropOffAtGate`	`boolean`
`routes[].route.roadCondition`	`object`
`routes[].route.roadCondition.roughM`	`number`
`routes[].route.country`	`string`
`routes[].route.warnings`	`string[]`
`routes[].route.fares`	`FareEstimate[]`
`routes[].route.fares[].mode`	`string`	Required. One of: `taxi`, `shared_taxi`, `okada`, `keke`, `bus`, `ridehail`, `boat`.
`routes[].route.fares[].service`	`string`
`routes[].route.fares[].currency`	`string`	Required. One of: `NGN`, `GHS`, `XOF`.
`routes[].route.fares[].low`	`integer`	Required.
`routes[].route.fares[].typical`	`integer`	Required.
`routes[].route.fares[].high`	`integer`	Required.
`routes[].route.fares[].text`	`string`	Required.
`routes[].route.fares[].perPerson`	`boolean`	Required.
`routes[].route.fares[].charter`	`boolean`	Required.
`routes[].route.fares[].night`	`boolean`
`routes[].route.fares[].rush`	`boolean`
`routes[].route.fares[].rain`	`boolean`
`routes[].route.fares[].basis`	`string`	Required. One of: `crowd`, `guide`.
`routes[].route.fares[].reports`	`integer`	Required.
`routes[].route.fares[].durationS`	`number`	Required.
`routes[].route.fares[].openingOffer`	`integer`	Where prices are haggled: a good first offer.
`routes[].route.fares[].sources`	`string (uri)[]`
`unassigned`	`string[]`	Required.
`notAllowed`	`object[]`	Stops, or vehicles' starts and ends, inside a ban area for the mode.
`notAllowed[].stop`	`string`
`notAllowed[].vehicle`	`string`
`notAllowed[].ban`	`Ban`	Required.
`notAllowed[].ban.id`	`string`	Required.
`notAllowed[].ban.zone`	`string`	Required.
`notAllowed[].ban.scope`	`string`	Required.
`notAllowed[].ban.hours`	`string`
`notAllowed[].ban.since`	`string`
`notAllowed[].ban.source`	`string (uri)`
`notAllowed[].ban.where`	`string`	One of: `origin`, `destination`, `stop`, `route`.
`notAllowed[].ban.walkM`	`number`
`durationS`	`number`	Required.
`mode`	`string`	Required.
`attribution`	`string`	Required.

200 OK

{
  "routes": [
    {
      "vehicle": "string",
      "stops": [
        "string"
      ],
      "durationS": 0,
      "distanceM": 0,
      "serviceS": 0,
      "load": 0,
      "arrivalsS": [
        0
      ],
      "route": {
        "distanceM": 0,
        "durationS": 0,
        "staticDurationS": 0,
        "trafficDelayS": 0,
        "speedSource": "live",
        "summary": "Admiralty Way and Awudu Ekpekha Boulevard",
        "geometry": {
          "type": "string",
          "coordinates": []
        },
        "legs": [
          {}
        ],
        "steps": [
          {}
        ],
        "segments": [
          {}
        ],
        "congestion": [
          {}
        ],
        "tolls": {
          "gates": [],
          "total": {
            "NGN": 300
          },
          "unknownPrices": 0
        },
        "borderCrossings": [
          {}
        ],
        "vehicleRules": {
          "vehicle": "okada",
          "avoided": [],
          "advice": [],
          "endBan": {},
          "allowedByRequest": [],
          "reported": []
        },
        "lastMile": {
          "stopAt": {},
          "stopName": "string",
          "mode": "string",
          "distanceM": 0,
          "durationS": 0,
          "geometry": {}
        },
        "access": {
          "kind": "estate",
          "text": "string",
          "name": "string",
          "gate": {},
          "dropOffAtGate": true
        },
        "roadCondition": {
          "roughM": 0
        },
        "country": "string",
        "warnings": [
          "string"
        ],
        "fares": [
          {}
        ]
      }
    }
  ],
  "unassigned": [
    "string"
  ],
  "notAllowed": [
    {
      "stop": "string",
      "vehicle": "string",
      "ban": {
        "id": "string",
        "zone": "Third Mainland Bridge",
        "scope": "string",
        "hours": "string",
        "since": "string",
        "source": "string",
        "where": "origin",
        "walkM": 0
      }
    }
  ],
  "durationS": 0,
  "mode": "string",
  "attribution": "string"
}

Errors

default Error