Tracking API

The Tracking API is designed to provide real-time shipment tracking and status updates.
This API enables businesses to track their shipments through different lifecycle stages such as pickup, transit, delivery, or return to origin (RTO). It ensures visibility and transparency for all stakeholders involved, while maintaining data accuracy and integrity.

Available Endpoints

POST Submits a new tracking update for a shipment
GET Retrieves tracking details of a specific shipment

Base URL

https://apis.prayog.io/tracking

Shipment Status Reference

The following table lists all available shipment statuses and their descriptions:

Status	Description
`order_confirmed`	Order has been confirmed and is ready for processing
`READY_FOR_DISPATCH`	Shipment is ready to be dispatched from the origin location
`inscan_at_hub`	Shipment has been scanned and received at a hub/facility
`outscan_at_hub`	Shipment has been scanned and dispatched from a hub/facility
`in_transit`	Shipment is currently in transit between locations
`out_for_delivery`	Shipment is out for delivery to the recipient
`delivered`	Shipment has been successfully delivered to the recipient
`rto`	Shipment is being returned to origin (Return to Origin)
`rto_out_for_delivery`	RTO shipment is out for delivery back to the sender
`rto_delivered`	RTO shipment has been delivered back to the sender
`cancelled`	Shipment has been cancelled
`lost`	Shipment has been reported as lost

1. 📦 Create Shipment Tracking Status Entry

POST /v2
Creates a new vehicle tracking entry with detailed origin, destination, and shipment data.

Headers

Content-Type: application/json
Authorization: Bearer token (if required)

Request Parameters

Field	Type	Description
`trackingId`	string	Unique ID for the tracking record
`cAwbNumber`	string	Carrier Air Waybill number
`smileAwbNumber`	string	Internal AWB number
`serviceType`	string	Type of service (e.g., STANDARD)
`travelType`	string	Mode of transport (e.g., AIR)
`documentType`	string	Type of document (e.g., DOX)
`originCenter`	string	Origin hub or center
`destinationCenter`	string	Destination hub or center
`bookingDate`	ISO string	Booking date in ISO 8601 format
`type`	string	Type of shipment (e.g., CARGO)
`source`	string	Source of the shipment (e.g., PRAYOG)
`childTrackingIds`	string[]	Child shipment AWB numbers for parent shipment booking (array of strings)

Sender Details

Field	Type	Description
`sender_mobile`	string	Sender’s mobile number
`sender_name`	string	Sender’s name

Receiver Details

Field	Type	Description
`receiver_mobile`	string	Receiver’s mobile number
`receiver_name`	string	Receiver’s name

Source Location

Field	Type	Description
`city`	string	City of origin
`state`	string	State of origin
`pincode`	string	Pincode of origin
`latititude`	string	Latitude (e.g., `22.5726° N`)
`longitude`	string	Longitude (e.g., `88.3639° E`)
`address`	string	Full address
`landmark`	string	Nearby landmark
`source`	string	Source of the shipment (e.g., PRAYOG)

Destination Location

Field	Type	Description
`city`	string	Destination city
`state`	string	Destination state
`pincode`	string	Destination pincode
`latititude`	string	Latitude (e.g., `18.5471° N`)
`longitude`	string	Longitude (e.g., `73.9470° E`)
`address`	string	Full destination address
`landmark`	string	Destination landmark

Status Payload

Field	Type	Description
`status`	string	Shipment status (e.g., `delivered`)
`trackingId`	string	Corresponding tracking ID
`cAwbNumber`	string	Carrier Air Waybill number
`deliveryPartnerName`	string	Name of delivery partner (e.g., `sevasetu`)
`statusTimestamp`	number	Epoch timestamp of the status update
`event`	string	Event name (e.g., `delivered`)
`location`	string	Hub or facility where the status was recorded

Request Body

{

  "orderInfo":{
  "trackingId": "2143243245",
  "cAwbNumber": "CAWDFEF1432435435",
  "smileAwbNumber": "67678556757656",
  "serviceType": "STANDARD",
  "travelType": "AIR",
  "documentType": "DOX",
  "originCenter": "NOIDA-SEC-66",
  "destinationCenter": "DELHI",
  "bookingDate": "DATE in ISO FORMAT",
  "type": "CARGO",
  "source": "PRAYOG",
  "childTrackingIds": ["CHILD_AWB_1", "CHILD_AWB_2"],
  "senderDetails": {
    "sender_mobile": "898979797",
    "sender_name": ""
  },
  "receiverDetails": {
    "receiver_mobile": "898979797",
    "receiver_name": ""
  },
  "sourceLocation": {
    "city": "KOLKATA",
    "state": "West Bengal",
    "pincode": "7000654",
    "latititude": "22.5726° N",
    "longitude": "88.3639° E",
    "address": "RashBehari Avenue Kolkata",
    "landmark": "Victoria Memorial"
  },
  "destinationLocation": {
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400002",
    "latititude": "18.5471° N",
    "longitude": "73.9470° E",
    "address": "Kalbadevi Pin Code",
    "landmark": "Victoria Memorial"
  }
  },
  "status":{
    "status":"delivered",
    "trackingId":"21432432457",
    "cAwbNumber":"CAWDFEF1432435435",
    "deliveryPartnerName":"sevasetu",
    "statusTimestamp": 1739446281,
    "event": "delivered",
    "location":"BENGALURU-HSR HUB GREEN GLAN LAYOUT"
  }
}

cURL Example

curl --request POST \
  --url https://apis.prayog.io/tracking/ \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_token>' \
  --data '{ ... }'

Success Response

{
  "message": "Tracking created successfully",
  "trackingId": "ARPAN12345",
  "status": "success"
}

Error Response

{
  "error": "Invalid request",
  "message": "Missing or invalid fields",
  "statusCode": 400
}

Insert Bulk Status Tracking

This endpoint allows you to insert status updates for multiple shipments in a single request. Use this API to efficiently update the status of bulk shipments.

POST /tracking/statuses/bulk

Request Body

Field	Type	Description
`trackingIds`	string[]	List of tracking IDs to update
`deliveryPartnerName`	string	Name of the delivery partner (e.g., sevasetu)
`status`	string	Status to be updated (e.g., MANIFESTED)
`statusTimestamp`	string	Epoch timestamp of the status update
`location`	string	Location where the status was recorded
`event`	string	Event name (e.g., MANIFESTED)

cURL Example

curl --location 'https://apis.prayog.io/tracking/statuses/bulk' \
--header 'Content-Type: application/json' \
--data '{
    "trackingIds": ["534534543", "4756765765"],
    "deliveryPartnerName": "sevasetu",
    "status": "MANIFESTED",
    "statusTimestamp": "1733930985",
    "location": "PUNE HUB",
    "event": "MANIFESTED"
}'

Get Statuses of Bulk Shipments

This endpoint allows you to fetch the statuses of multiple shipments in a single request by providing a comma-separated list of AWB numbers.

GET /tracking/bulk?awbNumbers=<awb1>,<awb2>,...

Query Parameters

Parameter	Type	Required	Description
`awbNumbers`	string	Yes	Comma-separated list of AWB numbers to fetch

cURL Example

curl --location 'https://apis.prayog.io/tracking/bulk?awbNumbers=23052931062409,27052931060258,27052931057257,22052931054451,27052931051254,23052931044406,27052931041252,27052931040251'

Success Response

[
  {
    "trackingId": "23052931062409",
    "status": "not_picked_up",
    "location": "DELHI JHANDEWALAN DC",
    "deliveryPartnerName": "shipsy",
    "statusTimestamp": "1743761965",
    "event": "",
    "cAwbNumber": "RZ23830452246",
    "createdAt": "2025-04-04T10:19:26.451Z",
    "category": "NOT_PICKED_UP"
  },
  {
    "trackingId": "27052931060258",
    "status": "not_picked_up",
    "location": "DELHI JHANDEWALAN DC",
    "deliveryPartnerName": "shipsy",
    "statusTimestamp": "1743761966",
    "event": "",
    "cAwbNumber": "RZ23830452245",
    "createdAt": "2025-04-04T10:19:26.298Z",
    "category": "NOT_PICKED_UP"
  }
  // ...more objects for each AWB number
]

Get Tracking Information by Tracking ID

This endpoint allows you to fetch tracking data for a specific shipment using its tracking ID (AWB number).

GET /tracking/v2/{trackingId}

Path Parameters

Parameter	Type	Required	Description
`trackingId`	string	Yes	The tracking ID (AWB number)

cURL Example

curl --location 'https://apis.prayog.io/tracking/v2/24010200568882' \
--header 'Content-Type: application/json'

Success Response

{
  "orderInformation": {
    "trackingId": "24010200568882",
    "smileAwbNumber": "24010200568882",
    "sourceLocation": {
      "city": "PUNE-411030",
      "state": "MAHARASHTRA",
      "pincode": "411030",
      "address": "SADHANA APRTMENT"
    },
    "destinationLocation": {
      "city": "BENGALURU",
      "state": "KARNATAKA",
      "pincode": "560102",
      "address": "......"
    },
    "senderDetails": {
      "sender_mobile": "7888011044"
    },
    "receiverDetails": {
      "receiver_mobile": "7888011044"
    },
    "documentType": "NON-DOX",
    "travelType": "Surface",
    "serviceType": "Standard",
    "bookingDate": "2025-02-11T11:43:14.963Z",
    "type": "COURIER"
  },
  "statuses": [
    {
      "status": "delivered",
      "location": "BENGALURU-HSR HUB GREEN GLAN LAYOUT",
      "deliveryPartnerName": "sevasetu",
      "receiverName": "Iqbal",
      "category": "DELIVERED",
      "subcategory": "Order has been delivered"
    },
    {
      "status": "out_for_delivery",
      "deliveryPartnerName": "drs",
      "category": "OUT_FOR_DELIVERY",
      "subcategory": "Shipment is out for delivery"
    }
  ]
}

3. 📹 Live Vehicle Streaming

This section explains how to implement real-time video streaming for tracking vehicles.

Vehicle Live Stream Integration

For implementing vehicle live streaming in your application, we recommend using the ws-mpegts-player package. This integration allows you to:

View real-time video feeds from vehicles
Monitor vehicle status visually
Enhance tracking capabilities with visual confirmation
Track by vehicle number to easily identify and stream specific vehicles

The package supports tracking by vehicle registration number, making it easy to locate and stream video from specific vehicles in your fleet.

For detailed implementation guides and usage examples, please refer to the ws-mpegts-player documentation.

Vehicle Path Tracker

A React component library for tracking and visualizing vehicle paths on maps using MapLibre GL. This package provides an easy-to-use interface for displaying vehicle GPS tracking data with interactive maps.

Features

🗺️ Interactive map visualization using MapLibre GL
🚗 Vehicle path plotting with start/end markers
📍 Clickable waypoints with detailed information
🎨 Built-in map styles and optimized dimensions
📊 Path statistics and information panels
🔄 Loading states and error handling
💾 TypeScript support with full type definitions
🔧 Simple API - just pass the vehicle ID

Installation

npm install vehicle-path-tracker

Dependencies

This package requires React 16.8+ and has the following peer dependencies:

npm install react react-dom

Usage

Basic Usage

import React from 'react';
import { VehiclePathTracker } from 'vehicle-path-tracker';

function App() {
  return (
    <div>
      <VehiclePathTracker vehicleId="WB25L5974" />
    </div>
  );
}

export default App;

With Callbacks

import React from 'react';
import { VehiclePathTracker } from 'vehicle-path-tracker';

function App() {
  const handlePathLoad = (data) => {
    console.log('Path loaded:', data);
  };

  const handleError = (error) => {
    console.error('Error:', error);
  };

  return (
    <div>
      <VehiclePathTracker
        vehicleId="WB25L5974"
        onPathLoad={handlePathLoad}
        onError={handleError}
      />
    </div>
  );
}

export default App;

With Road Snapping (New!)

import React from 'react';
import { VehiclePathTracker } from 'vehicle-path-tracker';

function App() {
  return (
    <div>
      <VehiclePathTracker
        vehicleId="WB25L5974"
        enableRoadSnapping={true}
        routingConfig={{
          provider: 'osrm' // or 'openrouteservice'
        }}
      />
    </div>
  );
}

export default App;

With OpenRouteService (Requires API Key)

import React from 'react';
import { VehiclePathTracker } from 'vehicle-path-tracker';

function App() {
  return (
    <div>
      <VehiclePathTracker
        vehicleId="WB25L5974"
        enableRoadSnapping={true}
        routingConfig={{
          provider: 'openrouteservice',
          apiKey: 'your-api-key-here'
        }}
      />
    </div>
  );
}

export default App;

Using the Map Component Directly

import React, { useState, useEffect } from 'react';
import { VehiclePathMap } from 'vehicle-path-tracker';

function CustomApp() {
  const [pathData, setPathData] = useState(null);

  useEffect(() => {
    // Your custom logic to fetch path data
    fetchPathData().then(setPathData);
  }, []);

  return (
    <div>
      {pathData && <VehiclePathMap pathData={pathData} />}
    </div>
  );
}

export default CustomApp;

API Reference

VehiclePathTracker Props

Prop	Type	Required	Description
`vehicleId`	`string`	Yes	Vehicle ID to track
`onPathLoad`	`(data: PathData) => void`	No	Callback when path data is loaded
`onError`	`(error: string) => void`	No	Callback when an error occurs
`enableRoadSnapping`	`boolean`	No	Enable road-following routes (default: false)
`routingConfig`	`RoutingConfig`	No	Routing service configuration

VehiclePathMap Props

Prop	Type	Required	Description
`pathData`	`PathData`	Yes	Path data to display on the map

Data Types

interface PathPoint {
  vehicleNumber: string;
  latitude: number;
  longitude: number;
  timestamp: string;
}

interface RoutePoint {
  latitude: number;
  longitude: number;
}

interface PathData {
  vehicleNumber: string;
  pathPoints: PathPoint[];
  totalPoints: number;
  originalDataPoints: number;
  jumpInterval?: number;
  dateRange?: {
    from: string;
    to: string;
  };
  roadRoute?: RoutePoint[]; // Road-snapped coordinates
  routingEnabled?: boolean;
}

interface RoutingConfig {
  provider: 'openrouteservice' | 'osrm';
  apiKey?: string; // Required for OpenRouteService
  profile?: 'driving-car' | 'cycling-regular' | 'foot-walking';
}

Configuration

The component comes with built-in configurations:

Map Style: MapTiler Streets style
Map Dimensions: 800x600 pixels
Auto-zoom: Automatically fits the path bounds
API Integration: Fetches data from vehicle tracking endpoints

Road Snapping Feature ��️

Overview

The road snapping feature converts GPS breadcrumbs into realistic road-following routes. Instead of straight lines between GPS points, it shows the actual paths vehicles would take on roads.

Supported Routing Providers

1. OSRM (Open Source Routing Machine) - FREE

No API key required
Good performance and accuracy
Default option for road snapping

2. OpenRouteService - FREE with API Key

Requires free API key registration
Higher accuracy in some regions
More customization options

Visual Display

When road snapping is enabled:

Blue solid line: Road-following route
Red dashed line: Original GPS points
Markers: Start, end, and waypoints remain on GPS coordinates

Limitations

Road snapping adds processing time
Requires internet connection
May not work for off-road vehicles
API rate limits may apply

Expected Data Format

The component expects tracking data in the following format:

{
  "status": 200,
  "data": {
    "vehicleNumber": "WB25L5974",
    "pathPoints": [
      {
        "vehicleNumber": "WB25L5974",
        "latitude": 22.6802983333333,
        "longitude": 88.4668783333333,
        "timestamp": "2025-06-16T04:48:01.256Z"
      }
    ],
    "totalPoints": 106,
    "originalDataPoints": 1048,
    "dateRange": {
      "from": "2025-06-16T04:46:47.627Z",
      "to": "2025-06-17T04:46:47.705Z"
    }
  }
}

Map Features

Start Point (🟢): Green marker indicating the first point in the path
End Point (🔴): Red marker indicating the last point in the path
Path Points (🟡): Yellow dots showing intermediate points (auto-filtered for clarity)
Path Line: Blue line connecting all points chronologically
Interactive Popups: Click any marker to see detailed information
Legend: Visual guide to understand map symbols
Info Panel: Displays vehicle information and statistics

Error Handling

The component handles various error scenarios:

Invalid or missing vehicle ID
Network connectivity issues
API response errors
No path data available

All errors are displayed in a user-friendly format and can be captured via the onError callback.

Browser Support

This component supports all modern browsers that support:

ES6+ features
WebGL (for MapLibre GL)
CSS Flexbox

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please use the GitHub Issues page.