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
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | ClickPost API key used for authentication. |
awb | string | Yes | Waybill of the shipment |
cp_id | integer | Yes | Partner 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 Name | Data Type | Description | Value Constraints |
|---|---|---|---|
meta | JSON Object | Metadata about the request, such as status codes and messages describing success or errors. Refer Possible Meta Statuses section below. | cannot be null |
result | JSON Object | The result data of the API request. | can be null or string if meta.success is false |
meta object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
message | string | Human-readable message indicating success or describing the error. | can be null or empty |
status | integer | Status code representing the result of the request (may include standard HTTP status codes). | cannot be null |
success | boolean | Indicates whether the request was processed successfully (true) or not (false). | cannot be null |
result object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
shipment_id | bigint / long | Unique ID of the shipment in ClickPost system for the given awb of the courier partner (cp_id) | cannot be null |
awb | string | Waybill of the order/shipment same as provided in the URL query params | cannot be null |
last_carrier_sync_time | timestamp | UTC 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:SS | can be null |
last_carrier_sync_status | string | Sync 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_location | JSON Object | Latest captured rider_location of the shipment. | can be null |
rider_locations | JSON array | List 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_locationsarray.
rider_location object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
location_id | uuid | Unique ID of the location captured in the ClickPost system | cannot be null |
shipment_id | bigint / long | Unique ID of the shipment in ClickPost system for the given awb of the courier partner (cp_id) | cannot be null |
latitude | double | Latitude of the rider location | cannot be null |
longitude | double | Longitude of the rider location | cannot be null |
location_capture_time | timestamp | UTC timestamp when the location data was captured from the courier partner's system. Format: YYYY-MM-DD HH:MM:SS | cannot be null |
creation_time | timestamp | UTC timestamp when the captured location was persisted in the ClickPost database. Format: YYYY-MM-DD HH:MM:SS | cannot be null |
Last Carrier Sync Status
| Status | Meaning |
|---|---|
| Location Information Retrieved Successfully | Carrier sync was successful and the rider's latitude/longitude coordinates were found. |
| Location Information Is Missing | Carrier sync was successful but the rider's latitude/longitude coordinates were missing. |
| Received Invalid Location Coordinates | Carrier sync was successful but received invalid rider's latitude/longitude coordinates. |
| Polling Request Update for shipment already executed After Scheduled Time | Rider’s latitude/longitude coordinates in the ClickPost system are already in sync with the carrier. |
| Bad Request Error from Courier Partner API | Received Bad Request (Http Status Code: 400) error while calling carrier’s Rider Location API. |
| Invalid Courier Partner API Credentials | Received Invalid Credentials error while calling carrier’s Rider Location API. |
| API Timeout From Courier Partner API | Received API Timeout error while calling carrier’s Rider Location API. |
| Authentication Failure from Courier Partner API | Received Unauthorized (Http Status Code: 401) error while calling carrier’s Rider Location API. |
| Forbidden from Courier Partner API | Received Forbidden (Http Status Code: 403) error while calling carrier’s Rider Location API. |
| Rate Limit Exceeded for Courier Partner API | Received Rate Limit Exceeded (Http Status Code: 429) error while calling carrier’s Rider Location API. |
| Internal Server Error from Courier Partner API | Received Internal Server Error (Http Status Code: 500) while calling carrier’s Rider Location API. |
| Network Error from Courier Partner API | A network connectivity issue occurred while attempting to communicate with the carrier’s Rider Location API. |
| Error in fetching Courier Partner API Credentials | Failed to retrieve the required API credentials for the carrier’s Rider Location API from the ClickPost system. |
Possible Meta Statuses
| HTTP Status Code | meta.status | meta.message |
|---|---|---|
| 200 | 200 | Request is executed successfully |
| 400 | 4001 | Invalid request json |
| 400 | 4002 | Request for invalid entity |
| 400 | 4003 | Invalid or missing query parameter |
| 400 | 4005 | User is not subscribed to the service |
| 401 | 4013 | Invalid API key |
| 403 | 403 | Access is not allowed |
| 404 | 4007 | API Not Found |
| 500 | 500 | Something went wrong in Clickpost server |
Example Responses
Success Response 1
For shipments with available rider location updates, the
rider_locationsarray contains location objects sorted bylocation_capture_timein 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
awbandcp_id.
{
"meta": {
"success": false,
"message": "Request for invalid entity",
"status": 4002
},
"result": "No shipment found"
}Updated 14 days ago
