NextRouteNextRoute

GPS Tracking API

API reference for submitting GPS pings from mobile devices, querying driver locations, route progress, and GPS history.

GPS Tracking API

The GPS Tracking API powers real-time driver location on the dispatch map. The driver mobile app submits GPS pings in batches, and dispatchers query driver positions and route overlay data. All endpoints require a valid JWT token.

Submit GPS Pings

The driver app calls this endpoint periodically (every 10-30 seconds) to report device location. Pings are submitted in batches to reduce network overhead.

curl -X POST "https://api.nextroute.app/api/gps/ping" \
  -H "Authorization: Bearer DRIVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "route_id": "route_abc123",
    "pings": [
      {
        "lat": 30.2672, "lng": -97.7431,
        "speed_mph": 25.5, "heading": 180,
        "accuracy_m": 5.2, "battery_pct": 78,
        "timestamp": "2026-03-24T14:30:00Z"
      },
      {
        "lat": 30.2680, "lng": -97.7425,
        "speed_mph": 30.1, "heading": 175,
        "accuracy_m": 4.8, "battery_pct": 77,
        "timestamp": "2026-03-24T14:30:15Z"
      }
    ]
  }'

Ping Object Fields:

FieldTypeRequiredDescription
latnumberYesLatitude
lngnumberYesLongitude
timestampstringYesISO 8601 timestamp from the device
speed_mphnumberNoSpeed in miles per hour
headingnumberNoCompass heading (0-360)
accuracy_mnumberNoGPS accuracy in meters
battery_pctnumberNoDevice battery percentage (0-100)

The route_id field on the request body is optional and associates pings with an active route. Pings are inserted in a single batch transaction. If any ping is missing required fields, the entire batch is rejected with 400.

Response (200): { "received": 2 }

Get All Driver Locations

Retrieve the latest GPS position for every active driver, along with their current route progress. This powers the live dispatch map.

curl "https://api.nextroute.app/api/gps/drivers" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "data": [
    {
      "id": "usr_driver1",
      "name": "Alex Rivera",
      "role": "driver",
      "location": {
        "lat": 30.2672, "lng": -97.7431,
        "speed_mph": 25.5, "heading": 180,
        "battery_pct": 78,
        "timestamp": "2026-03-24T14:30:00Z"
      },
      "route": {
        "id": "route_abc123",
        "name": "Central Austin - Monday",
        "status": "in_progress",
        "planned_stops": 45,
        "completed_stops": 22
      }
    }
  ]
}

Drivers without a recent GPS ping return location: null. Drivers without a route today return route: null. Both drivers and admins are included.

Get Latest Ping for a Driver

Retrieve the most recent GPS ping for a specific driver. Dispatchers can query any user; drivers default to their own position.

curl "https://api.nextroute.app/api/gps/latest?user_id=usr_driver1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns 404 if no GPS data exists for the user. The user_id parameter is optional and defaults to the authenticated user.

Routes Overview (Map Overlay)

Get all routes and their stops for a given date, grouped by route, with coordinates and zone colors for map rendering.

curl "https://api.nextroute.app/api/gps/routes-overview?date=2026-03-24" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "data": [
    {
      "route_id": "route_abc123",
      "route_name": "Central Austin - Monday",
      "route_status": "in_progress",
      "zone_color": "#3B82F6",
      "stops": [
        {
          "id": "stop_001", "status": "completed", "sequence": 1,
          "lat": 30.2672, "lng": -97.7431,
          "customer_name": "John Doe",
          "address": "123 Main St, Austin, TX 78701"
        }
      ]
    }
  ]
}

The date parameter defaults to today if omitted. Stops without coordinates are excluded.

GPS History for a Route

Retrieve the full GPS track for a specific route, useful for playback and audit trails.

curl "https://api.nextroute.app/api/gps/history?route_id=route_abc123&since=2026-03-24T12:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"
ParameterTypeRequiredDescription
route_idstringYesThe route to fetch history for
sincestringNoOnly return pings after this ISO timestamp

Results are ordered by timestamp ASC (oldest first). The since parameter supports incremental polling by passing the timestamp of the last received ping.

Route Templates API

API reference for master routes — list, create, manage stops, approve pending stops, reorder, optimize, generate daily routes, and clone templates.

Enrollment API

API reference for the public enrollment flow — form configuration, address validation, promo codes, and lead submission with auto-enroll or manual review.