Track deliveries – API docs

There are three ways to follow a delivery. Most integrations combine them:

Need	Use
The recipient wants to see where the courier is	Share `tracking_url`. Maxmove hosts the page.
Your system needs to know the status	Webhooks.
Your own UI shows the courier on a map or an ETA	Poll `GET /v1/deliveries/{deliveryId}/tracking`.

Code examples use BASE_URL and headers from the Quickstart.

Every live delivery has a tracking_url, for example https://maxmove.com/de/track/3J8kQ2pVx9. Send it to the recipient by e-mail or SMS, or link it from your order page. It needs no login and shows the live status, the courier's position when it is available, and the ETA.

Read the tracking snapshot#

The tracking endpoint returns:

Field	Meaning
`status`	Current delivery status.
`eta_seconds`	Expected seconds until the courier reaches the next waypoint.
`distance_meters`	Remaining driving distance to the next waypoint.
`route_polyline`	Remaining route as an encoded polyline (Google format).
`courier.name`, `courier.photo_url`, `courier.rating`	Courier first name, profile photo, and average rating, so the recipient knows who to expect.
`courier.vehicle`	`make`, `model`, `color`, `license_plate`, and `photo_url` of the vehicle.
`courier.location`	Latitude, longitude, and `recorded_at`. `null` until `tracking_available_at`.
`tracking_available_at`	When the position becomes available. Scheduled deliveries open tracking before pickup.

Poll only while it matters#

Poll the endpoint only for deliveries a person is looking at, and only while the courier is on the way:

Start when the status is courier_assigned, or at tracking_available_at for scheduled deliveries.
Poll every 15 to 30 seconds. Positions don't change faster than that in a useful way.
Stop at delivered or cancelled.
Use the delivery.eta_updated webhook to refresh an ETA you show elsewhere: the event itself carries no ETA.

Each key can make 600 requests per minute in live mode. See Rate limits.

import { decode } from '@googlemaps/polyline-codec';
 
const ACTIVE = new Set(['courier_assigned', 'at_pickup', 'picked_up', 'in_transit', 'at_dropoff']);
 
async function pollTracking(deliveryId: string, onUpdate: (snapshot: unknown) => void) {
  while (true) {
    const tracking = await fetch(`${BASE_URL}/deliveries/${deliveryId}/tracking`, { headers }).then(
      (res) => res.json(),
    );
    const route = tracking.route_polyline ? decode(tracking.route_polyline) : [];
    onUpdate({ ...tracking, route });
    if (!ACTIVE.has(tracking.status) && tracking.status !== 'pending') return;
    await new Promise((resolve) => setTimeout(resolve, 20_000));
  }
}

import time
import polyline  # pip install polyline
 
ACTIVE = {"courier_assigned", "at_pickup", "picked_up", "in_transit", "at_dropoff"}
 
def poll_tracking(delivery_id, on_update):
    while True:
        tracking = requests.get(f"{BASE_URL}/deliveries/{delivery_id}/tracking", headers=headers).json()
        route = polyline.decode(tracking["route_polyline"]) if tracking["route_polyline"] else []
        on_update({**tracking, "route": route})
        if tracking["status"] not in ACTIVE and tracking["status"] != "pending":
            return
        time.sleep(20)

Webhook payloads carry only the courier's name, because they end up in logs. Read the photo, vehicle, and position from the tracking endpoint when you need them.

In test mode#

The Robocourier moves in a straight line from pickup to dropoff and reports a position at every step, so you can test a map view without a real courier.

Share the tracking page#

Read the tracking snapshot#

Poll only while it matters#

In test mode#