Get Rider Location

Provides rider location updates (latitude and longitude) for the HLD shipments.

Prerequisites

  • Required Service has to be enabled. (ClickPost starts fetching rider location updates from courier partner after the service is activated).
  • Once Rider Location Service is enabled, enterprise can use the ClickPost Rider Location API to poll for rider location updates for any shipment of the HLD courier.

Note: Contact the ClickPost team for assistance with setup and service enablement.

Rider Location API

Allowed HTTP Methods

  • GET

URL

<baseURL>/api/v1/quickcom/rider_location

baseURL - https://hld.clickpost.in

URL Query Parameters

ParameterTypeRequiredDescription
keystringYesClickPost API key used for authentication.
awbstringYesWaybill of the shipment
cp_idintegerYesPartner ID of the courier integrated in the ClickPost. Find here

Sample API cURL

curl --location --request GET '<baseURL>/api/v1/quickcom/rider_location?key=<API_KEY>&awb=AWB123&cp_id=123' \
--header 'Content-Type: application/json'

Response JSON Format

Field NameData TypeDescriptionValue Constraints
metaJSON ObjectMetadata about the request, such as status codes and messages describing success or errors. Refer Possible Meta Statuses section below.cannot be null
resultJSON ObjectThe result data of the API request.can be null or string if meta.success is false

meta object fields

Field NameData TypeDescriptionValue Constraints
messagestringHuman-readable message indicating success or describing the error.can be null or empty
statusintegerStatus code representing the result of the request (may include standard HTTP status codes).cannot be null
successbooleanIndicates whether the request was processed successfully (true) or not (false).cannot be null

result object fields

Field NameData TypeDescriptionValue Constraints
shipment_idbigint / longUnique ID of the shipment in ClickPost system for the given awb of the courier partner (cp_id)cannot be null
awbstringWaybill of the order/shipment same as provided in the URL query paramscannot be null
last_carrier_sync_timetimestampUTC timestamp indicating when the carrier's location was last synced in the Clickpost system (via API call or webhook). Format: YYYY-MM-DD HH:MM:SScan be null
last_carrier_sync_statusstringSync status of the location sync attempt that occurred at last_carrier_sync_time, indicating whether the sync was succeeded or skipped/failed with a specific error. Refer to Last Carrier Sync Status section below to know the possible list of statuses and their meaning.can be null
latest_rider_locationJSON ObjectLatest captured rider_location of the shipment.can be null
rider_locationsJSON arrayList of captured rider_location objects sorted by location_capture_time in descending order.can be empty

NOTE: Only change log of the rider locations will be included in the rider_locations array.

rider_location object fields

Field NameData TypeDescriptionValue Constraints
location_iduuidUnique ID of the location captured in the ClickPost systemcannot be null
shipment_idbigint / longUnique ID of the shipment in ClickPost system for the given awb of the courier partner (cp_id)cannot be null
latitudedoubleLatitude of the rider locationcannot be null
longitudedoubleLongitude of the rider locationcannot be null
location_capture_timetimestampUTC timestamp when the location data was captured from the courier partner's system. Format: YYYY-MM-DD HH:MM:SScannot be null
creation_timetimestampUTC timestamp when the captured location was persisted in the ClickPost database. Format: YYYY-MM-DD HH:MM:SScannot be null

Last Carrier Sync Status

StatusMeaning
Location Information Retrieved SuccessfullyCarrier sync was successful and the rider's latitude/longitude coordinates were found.
Location Information Is MissingCarrier sync was successful but the rider's latitude/longitude coordinates were missing.
Received Invalid Location CoordinatesCarrier sync was successful but received invalid rider's latitude/longitude coordinates.
Polling Request Update for shipment already executed After Scheduled TimeRider’s latitude/longitude coordinates in the ClickPost system are already in sync with the carrier.
Bad Request Error from Courier Partner APIReceived Bad Request (Http Status Code: 400) error while calling carrier’s Rider Location API.
Invalid Courier Partner API CredentialsReceived Invalid Credentials error while calling carrier’s Rider Location API.
API Timeout From Courier Partner APIReceived API Timeout error while calling carrier’s Rider Location API.
Authentication Failure from Courier Partner APIReceived Unauthorized (Http Status Code: 401) error while calling carrier’s Rider Location API.
Forbidden from Courier Partner APIReceived Forbidden (Http Status Code: 403) error while calling carrier’s Rider Location API.
Rate Limit Exceeded for Courier Partner APIReceived Rate Limit Exceeded (Http Status Code: 429) error while calling carrier’s Rider Location API.
Internal Server Error from Courier Partner APIReceived Internal Server Error (Http Status Code: 500) while calling carrier’s Rider Location API.
Network Error from Courier Partner APIA network connectivity issue occurred while attempting to communicate with the carrier’s Rider Location API.
Error in fetching Courier Partner API CredentialsFailed to retrieve the required API credentials for the carrier’s Rider Location API from the ClickPost system.

Possible Meta Statuses

HTTP Status Codemeta.statusmeta.message
200200Request is executed successfully
4004001Invalid request json
4004002Request for invalid entity
4004003Invalid or missing query parameter
4004005User is not subscribed to the service
4014013Invalid API key
403403Access is not allowed
4044007API Not Found
500500Something went wrong in Clickpost server

Example Responses

Success Response 1

For shipments with available rider location updates, the rider_locations array contains location objects sorted by location_capture_time in descending order.

{
  "meta": {
    "success": true,
    "message": "Request is executed successfully",
    "status": 200
  },
  "result": {
    "shipment_id": 123456789,
    "awb": "AWB123",
    "last_carrier_sync_time": "2025-04-01 12:42:40",
    "last_carrier_sync_status": "Location Information Retrieved Successfully",
    "latest_rider_location": {
      "location_id": "550e8400-e29b-41d4-a716-446655440002",
      "shipment_id": 123456789,
      "latitude": 28.613934,
      "longitude": 77.209095,
      "location_capture_time": "2025-04-01 12:30:40",
      "creation_time": "2025-04-01 12:30:40"
    },
    "rider_locations": [
      {
        "location_id": "550e8400-e29b-41d4-a716-446655440002",
        "shipment_id": 123456789,
        "latitude": 28.613934,
        "longitude": 77.209095,
        "location_capture_time": "2025-04-01 12:30:40",
        "creation_time": "2025-04-01 12:30:40"
      },
      {
        "location_id": "550e8400-e29b-41d4-a716-446655440001",
        "shipment_id": 123456789,
        "latitude": 28.613931,
        "longitude": 77.209091,
        "location_capture_time": "2025-04-01 12:30:10",
        "creation_time": "2025-04-01 12:30:11"
      },
      {
        "location_id": "550e8400-e29b-41d4-a716-446655440000",
        "shipment_id": 123456789,
        "latitude": 28.614031,
        "longitude": 77.20889,
        "location_capture_time": "2025-04-01 12:29:40",
        "creation_time": "2025-04-01 12:29:40"
      }
    ]
  }
}

Success Response 2

When no rider location updates are available for a shipment

{
  "meta": {
    "success": true,
    "message": "Request is executed successfully",
    "status": 200
  },
  "result": {
    "shipment_id": 1234567890,
    "awb": "AWB123",
    "last_carrier_sync_time": null,
    "last_carrier_sync_status": null,
    "latest_rider_location": null,
    "rider_locations": []
  }
}

Error Response 1

When an enterprise has not subscribed to the Rider Location Service.

{
  "meta": {
    "success": false,
    "message": "User is not subscribed to the service",
    "status": 4005
  },
  "result": "Enterprise User Is Not Subscribed To Use the service: {ServiceCode: 109, ServiceName: Quick Commerce Shipment Rider Location}"
}

Error Response 2

When ClickPost has not integrated a courier partner for rider location updates.

{
  "meta": {
    "success": false,
    "message": "User is not subscribed to the service",
    "status": 4005
  },
  "result": "Rider Location Service is not supported for this courier partner"
}

Error Response 3

When no shipment found for the provided awb and cp_id.

{
  "meta": {
    "success": false,
    "message": "Request for invalid entity",
    "status": 4002
  },
  "result": "No shipment found"
}

Did this page help you?