Skip to main content

​
Pinger API Overview

The Pinger API allows driver apps to broadcast the current location of drivers, indicating their availability for new jobs. This is particularly useful for deadheads (empty return trips) where drivers can signal their availability after completing a drop-off. When a driver completes a trip and becomes available, they can use the Pinger service to broadcast their location. Clients and other services can then check who is available in a specific location, making it easier to match available drivers with new ride requests.

​
Use Case Example

A driver named “Alex GNet” drops off a passenger at LAX airport. After the drop-off, the driver can report their Pinger location, which tells the system that they are available to pick up new jobs. This helps optimize driver utilization and reduces deadhead time.

​
Endpoint

POST https://location.grdd.net/api/gping

​
Authentication

No authentication is required for this endpoint. You can post location broadcasts without providing any authentication tokens or credentials.

​
Request Headers

Content-Type: application/json

​
Request Body Schema

The request body should contain the following fields:
FieldTypeRequiredDescription
colorstringNoColor identifier for the driver/vehicle
driverActivebooleanYesIndicates if the driver is currently active and available
driveridstringYesUnique identifier for the driver
griddidstringYesThe GNet provider identifier (griddid)
latstringYesLatitude coordinate of the driver’s current location
lonstringYesLongitude coordinate of the driver’s current location
namestringYesDriver’s name
phonestringNoDriver’s phone number
paxcountstringNoPassenger capacity of the vehicle
showPublicbooleanYesWhether to make this location visible publicly
vehicleTypestringNoType of vehicle (e.g., SUV, Sedan, Van)
vehmakestringNoVehicle manufacturer (e.g., Mercedes, BMW)
vehmodelstringNoVehicle model (e.g., EQS, S-Class)
vehyearstringNoVehicle year

​
Example Request Body

{
    "color": "red",
    "driverActive": true,
    "driverid": "42",
    "griddid": "gnettest",
    "lat": "40.7285648921236",
    "lon": "-74.0048338381179",
    "name": "Alex  GNet",
    "phone": "444",
    "paxcount": "8",
    "showPublic": true,
    "vehicleType": "SUV",
    "vehmake": "Mercedes",
    "vehmodel": "EQS",
    "vehyear": "2025"
}

​
Example cURL Request

curl --location 'https://location.grdd.net/api/gping' \
--header 'Content-Type: application/json' \
--data '{
    "color":"red",
    "driverActive":true,
    "driverid":"42",
    "griddid":"gnettest",
    "lat":"40.7285648921236",
    "lon":"-74.0048338381179",
    "name":"Alex  GNet",
    "phone":"444",
    "paxcount":"8",
    "showPublic":true,
    "vehicleType":"SUV",
    "vehmake":"Mercedes",
    "vehmodel":"EQS",
    "vehyear":"2025"
}'

​
Response

The API will return a response indicating whether the location broadcast was successful. The exact response format may vary based on your configuration.

​
Success Response

{
    "success": true,
    "message": "Gping saved"
}

​
Error Response

{
    "success": false,
    "message": "Error message describing what went wrong"
}

​
Get Available Pingers

You can retrieve a list of currently available pingers (drivers who have broadcast their availability) for a specific provider.

​
Get Pingers Endpoint

GET https://location.grdd.net/api/getPingers/{griddid}/v1 Replace {griddid} with the GNet provider identifier.

​
Authentication

Authentication is required for this endpoint. You must provide a valid token in the request header. To obtain an access token, see the Get Token API documentation.

​
Request Headers

token: <your_access_token>

​
Example cURL Request

curl --location 'https://location.grdd.net/api/getPingers/gnettest/v1' \
--header 'token: YOUR_ACCESS_TOKEN'

​
Response

The API returns an array of available pingers with their current location and availability information.

​
Success Response

[
    {
        "color": "red",
        "driverActive": true,
        "driverid": "42",
        "griddid": "gnettest",
        "lat": "40.7285648921236",
        "lon": "-74.0048338381179",
        "name": "Alex  GNet",
        "phone": "444",
        "paxcount": "8",
        "showPublic": true,
        "vehicleType": "SUV",
        "vehmake": "Mercedes",
        "vehmodel": "EQS",
        "vehyear": "2025"
    }
]

​
Empty Response

If no pingers are available, the API returns an empty array: 
[]

​
Error Response

{
    "success": false,
    "message": "Error message describing what went wrong"
}

​
Best Practices

  1. Update Frequency: Broadcast location updates when the driver becomes available or when their location changes significantly (e.g., after completing a trip).
  2. Deadhead Optimization: Use Pinger after drop-offs to signal availability, helping reduce empty return trips.
  3. Location Accuracy: Ensure lat and lon values are accurate GPS coordinates for better matching with ride requests.
  4. Driver Status: Set driverActive to true only when the driver is actually available to accept new jobs.
  5. Public Visibility: Use showPublic to control whether the driver’s location should be visible to other services and clients.
  • Save GPS - Save GPS location for active reservations
  • Get GPS - Retrieve GPS location of active reservations
  • GPS Grab - Grab GPS location data

​
Need Help?

Contact Support

Our support team is here to help you with integration questions and troubleshooting.