Pinger

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:

Field	Type	Required	Description
`color`	string	No	Color identifier for the driver/vehicle
`driverActive`	boolean	Yes	Indicates if the driver is currently active and available
`driverid`	string	Yes	Unique identifier for the driver
`griddid`	string	Yes	The GNet provider identifier (griddid)
`lat`	string	Yes	Latitude coordinate of the driver’s current location
`lon`	string	Yes	Longitude coordinate of the driver’s current location
`name`	string	Yes	Driver’s name
`phone`	string	No	Driver’s phone number
`paxcount`	string	No	Passenger capacity of the vehicle
`showPublic`	boolean	Yes	Whether to make this location visible publicly
`vehicleType`	string	No	Type of vehicle (e.g., SUV, Sedan, Van)
`vehmake`	string	No	Vehicle manufacturer (e.g., Mercedes, BMW)
`vehmodel`	string	No	Vehicle model (e.g., EQS, S-Class)
`vehyear`	string	No	Vehicle 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

Update Frequency: Broadcast location updates when the driver becomes available or when their location changes significantly (e.g., after completing a trip).
Deadhead Optimization: Use Pinger after drop-offs to signal availability, helping reduce empty return trips.
Location Accuracy: Ensure lat and lon values are accurate GPS coordinates for better matching with ride requests.
Driver Status: Set driverActive to true only when the driver is actually available to accept new jobs.
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.

Getting Started

Company & Users

Partners

Fleet

Location

Content

Bookings

Pinger API Overview

Use Case Example

Endpoint

Authentication

Request Headers

Request Body Schema

Example Request Body

Example cURL Request

Response

Success Response

Error Response

Get Available Pingers

Get Pingers Endpoint

Authentication

Request Headers

Example cURL Request

Response

Success Response

Empty Response

Error Response

Best Practices

Need Help?

Contact Support

​Pinger API Overview

​Use Case Example

​Endpoint

​Authentication

​Request Headers

​Request Body Schema

​Example Request Body

​Example cURL Request

​Response

​Success Response

​Error Response

​Get Available Pingers

​Get Pingers Endpoint

​Authentication

​Request Headers

​Example cURL Request

​Response

​Success Response

​Empty Response

​Error Response

​Best Practices

​Related APIs

​Need Help?

Contact Support

Pinger API Overview

Use Case Example

Endpoint

Authentication

Request Headers

Request Body Schema

Example Request Body

Example cURL Request

Response

Success Response

Error Response

Get Available Pingers

Get Pingers Endpoint

Authentication

Request Headers

Example cURL Request

Response

Success Response

Empty Response

Error Response

Best Practices

Related APIs

Need Help?