Skip to main content

GPS Grab API Overview

Provider can save multiple GPS locations of active reservations in a single API call. This endpoint is designed for bulk GPS location updates, allowing providers to send multiple location data points efficiently. You can call this API as many times as you want. But not more than 1 times per second.

Endpoint

POST https://location.grdd.net/api/GGPS.svc/GPSgrab

Request Body Schema

export const GPSGrabSchema = z.object({
  // The GPSGrabSchema itself is now an array of location objects, not an object with a 'locations' property
  z.array(z.object({
    griddid: z.string().nullish().describe("griddid: the grid id of the provider"),
    internalBookingId: z.string().nullish().describe("internalBookingId: the internal booking id of the reservation"),
    chfName: z.string().nullish().describe("the name of the chauffeur"),
    direction: z
      .object({
        heading: z.string().nullish().describe("heading: the heading of the vehicle"),
        magnitude: z.string().nullish().describe("magnitude: the magnitude of the vehicle"),
        unit: z.string().nullish().describe("unit: the unit of the vehicle"),
      })
      .nullish(),
    driverId: z.string().nullish().describe("driverId: the id of the driver"),
    headingDir: z.string().nullish().describe("headingDir: the heading direction of the vehicle"),
    latitude: z.coerce.number().nullish().describe("latitude: the latitude of the vehicle"),
    locationDateTime: z.string().transform((str) => new Date(str)),
    longitude: z.coerce.number().nullish().describe("longitude: the longitude of the vehicle"),
    phoneNo: z.string().nullish().describe("phoneNo: the phone number of the driver"),
    picURL: z.string().nullish().describe("picURL: the picture url of the driver"),
    systemId: z.string().nullish().describe("systemId: the system id of the vehicle"),
    transactionId: z.string().nullish().describe("transactionId: the transaction id of the reservation"),
    vehicleId: z.string().nullish().describe("vehicleId: the id of the vehicle"),
    status: z.string().nullish().describe("status: EN_ROUTE, ON_LOCATION, PASSENGER_ON_BOARD, etx"),
    from: z.string().nullish().describe("from: requester or provider"),
  })).describe("Array of GPS location objects")
});

Example Request Body

 [
    {
      "chfName": "Alex Jones",
      "direction": {
        "heading": "",
        "magnitude": "",
        "unit": ""
      },
      "driverId": "",
      "griddid": "gnettest",
      "headingDir": null,
      "internalBookingId": "H123456",
      "latitude": "51.543400",
      "locationDateTime": "2025-06-04T18:41:39",
      "longitude": "-0.373100",
      "phoneNo": "+15005005000",
      "picURL": "https://www.gravatar.com/avatar/2c7d99fe281ecd3bcd65ab915bac6dd5?s=250",
      "systemId": null,
      "transactionId": "11111111-3ef3-4168-a815-8f7d5e2ea36b",
      "vehicleId": "123",
      "status": "EN_ROUTE",
      "from": "provider"
    },
    {
      "chfName": "Sarah Wilson",
      "direction": {
        "heading": "180",
        "magnitude": "45",
        "unit": "km/h"
      },
      "driverId": "DRV002",
      "griddid": "gnettest",
      "headingDir": "South",
      "internalBookingId": "H789012",
      "latitude": "51.507400",
      "locationDateTime": "2025-06-04T18:42:15",
      "longitude": "-0.127800",
      "phoneNo": "+15005005001",
      "picURL": "https://www.gravatar.com/avatar/3d7d99fe281ecd3bcd65ab915bac6dd6?s=250",
      "systemId": "SYS002",
      "transactionId": "22222222-4ef4-4168-a815-8f7d5e2ea36c",
      "vehicleId": "456",
      "status": "ON_LOCATION",
      "from": "provider"
    }
  ]


Success Responses

200 - Success

Returned when all GPS locations are successfully saved. Standard Success Response:
{
    "status": "OK"
}

Error Responses

400 - Bad Request

Returned when the request body is invalid or missing required fields.
{
  "success": false,
  "status": 400,
  "error": "Invalid request format: locations array is required"
}

500 - Internal Server Error

Returned when there’s a server-side error processing the request.
{
  "success": false,
  "status": 500,
  "error": "Internal server error occurred while processing GPS locations"
}
I