Submit A Location Ping

Developing

POST

/api/v1/public/geolocation

Records a device location ping for a customer and scores it against the customer's registered home coordinates. Pings are cached per customer at roughly 11-metre resolution, so near-identical coordinates return the earlier stored result rather than creating a new row. The wallet is debited on every call, cache hit or not. When the customer is unknown to your company, or has no stored coordinates, the ping is still recorded and charged but scores 0.

Request

Authorization

API Key

Add parameter in header

X-Api-Key

Example:

X-Api-Key: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Ping recorded and scored.

Bodyapplication/json

🟠401

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/public/geolocation' \
--header 'X-Api-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "latitude": 6.4295,
    "longitude": 3.4211,
    "customerId": "CUST-000412"
}'

Response Example

200 - Example 1

{
    "status": true,
    "message": "Operation successful.",
    "data": {
        "id": 0,
        "latitude": 0,
        "longitude": 0,
        "formattedAddress": "string",
        "customerId": "string",
        "fullName": "string",
        "customerPhone": "string",
        "timestamp": "2019-08-24T14:15:22.123Z",
        "proximityScore": 94.5,
        "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
        "createdBy": "string",
        "createdAt": "2019-08-24T14:15:22.123Z"
    }
}

Modified at 2026-08-06 11:58:31

Get A Bulk Geocode Job

Verify A BVN