Fleet tracking

What it does

• Vehicles and drivers: your bikes, cars and vans, with who rides them and their last known position.
• Positions: your rider app sends GPS fixes in batches; N-Ways keeps them as trip history.
• Deliveries (tasks): a pickup and a drop-off, assigned to a vehicle, with an arrival time that N-Ways keeps up to date from the rider’s position, live traffic and reported incidents.
• Tracking links: a page your customer opens to watch the rider come, with no app and no sign-in.
• Webhooks: your server hears when a delivery is assigned, the rider is arriving, the delivery is done or failed, or a vehicle goes quiet.
• Alerts: told by email, push or webhook when a vehicle leaves its area, enters a zone, goes silent or stops too long; forwarded to Excel, Google Sheets or Telegram.

Base address: https://nways.ng/maps/v1/fleet. Fleet calls change your data, so use a key restricted to your servers’ IP addresses, or to your rider app (Android package and SHA-1, or iOS bundle ID). Never use a fleet key in a web page.

A delivery from start to end

1. Add your vehicles once, with your own IDs: POST /vehicles {"id": "bike-17", "mode": "motorcycle"}. motorcycle means a commercial okada: its arrival times keep to okada bans.
2. Create the delivery with your order number as its ID: POST /tasks, with the dropoff (and a pickup if the rider collects first). Give vehicleId to assign it at once, or later with POST /tasks/{id}/assign. Keep your stores and warehouses as pickup places and send pickupPlaceId instead of a pickup. Your customers and each one’s addresses come back from GET /customers, for the next delivery to them.
3. Change it if plans change: PATCH /tasks/{id} with only what changes (the drop-off, the due time, the recipient…). Everything can change until it’s picked up; after that, only notes and dueAt. The tracking link stays the same, the arrival time is worked out again, the rider is told, and you get task.updated.
4. Send positions from the rider app every 5 to 15 seconds while on a delivery: POST /locations with up to 1,000 fixes. An app that was offline sends what it buffered (up to 24 hours old).
5. Share the link: the task’s trackingUrl (or POST /tasks/{id}/share for a fresh one) goes in your SMS or WhatsApp message to the customer.
6. Mark the steps: POST /tasks/{id}/pickup when the rider has the parcel, then /complete (or /fail, /cancel). The task becomes arriving by itself when the rider is close.

# Create a delivery, assigned to bike-17
curl -X POST "https://nways.ng/maps/v1/fleet/tasks" \
  -H "X-NWays-Api-Key: YOUR_SERVER_KEY" -H "Content-Type: application/json" \
  -d '{"id": "order-1041", "vehicleId": "bike-17", "pickup": {"lat": 6.5965, "lng": 3.3421, "name": "Kitchen, Ikeja GRA"}, "dropoff": {"lat": 6.6018, "lng": 3.3515, "address": "12 Allen Avenue, Ikeja"}}'

# The rider app sends its position
curl -X POST "https://nways.ng/maps/v1/fleet/locations" \
  -H "X-NWays-Api-Key: YOUR_APP_KEY" -H "Content-Type: application/json" \
  -d '{"updates": [{"vehicleId": "bike-17", "lat": 6.5981, "lng": 3.3460, "speedMps": 6.2, "heading": 80}]}'

# Where is it, and when will it arrive?
curl "https://nways.ng/maps/v1/fleet/tasks/order-1041" -H "X-NWays-Api-Key: YOUR_SERVER_KEY"

const fleet = (path, init = {}) =>
  fetch('https://nways.ng/maps/v1/fleet' + path, {
    ...init,
    headers: { 'X-NWays-Api-Key': process.env.NWAYS_SERVER_KEY, 'Content-Type': 'application/json' },
  }).then(async (res) => {
    const data = await res.json()
    if (!res.ok) throw new Error(`${data.error.reason}: ${data.error.message}`)
    return data
  })

const task = await fleet('/tasks', {
  method: 'POST',
  body: JSON.stringify({
    id: 'order-1041',
    vehicleId: 'bike-17',
    pickup: { lat: 6.5965, lng: 3.3421, name: 'Kitchen, Ikeja GRA' },
    dropoff: { lat: 6.6018, lng: 3.3515, address: '12 Allen Avenue, Ikeja' },
  }),
})
console.log('Send the customer:', task.trackingUrl)

Arrival times

A task’s eta has the arrival time (at), the time and distance left, the part of the time due to traffic (trafficDelayS) and, before pickup, when the rider reaches the pickup (pickupAt). It’s worked out again from each fresh position (at most every 10 seconds a task), with live traffic and reported incidents, and is null until a position is in.

Tracking links

A tracking link such as https://nways.ng/t/3fT9kQ2xVbN7LmP0aZc4RwYe opens a page with the rider on the map, the drop-off and the arrival time, in English or French (the task’s lang), under your brandName (PUT /settings). It shows no names or phone numbers, and the rider only while the delivery is under way. A link works for 72 hours, or until an hour after the delivery ends. To build a page of your own instead, see the delivery tracking sample.

Your data

• Positions are kept as trip history for retentionDays (30 by default, 1 to 90), then deleted. GET /vehicles/{id}/history returns them.
• Arrival times and traffic figures serve that trip only: they’re cleared when the task ends.
• Your positions feed N-Ways’ public live traffic only if you turn on shareTraffic; then they’re used anonymously, like any phone’s. It’s off unless you turn it on.
• Tell your riders their position is shared while they work, as your local data protection law requires.

Limits

6,000 fleet calls a minute per key by default; up to 1,000 positions in one POST /locations; up to 10 webhook endpoints. IDs are yours: 1 to 64 letters, digits and _ . : -, unique in your project. Quotas and limits