Get Nearby Agents API

Overview

Find and retrieve nearby agent users within a specified geographical radius using geospatial search capabilities.

API Details

Method: GET
URL: https://api.gafapay.com:8443/gafapay/v3/user/get_nearby_agents
Content-Type: application/json
companyid: 59388167894b4d10a04fe5da3b8a2104
requestid: b35d332f-131e-44c1-892f-8322e022da74
Authorization: Token required

Endpoint

GET https://api.gafapay.com:8443/gafapay/v3/user/get_nearby_agents

Query Parameters

Required Parameters

latitude (Double): User's current latitude coordinate
- Example: 14.733333333333333
- Range: -90 to 90
longitude (Double): User's current longitude coordinate
- Example: -17.633333
- Range: -180 to 180
radius (Double): Search radius in meters
- Example: 1000000 (1,000,000 meters = 1000 km)
- Minimum: 1 meter

Optional Parameters

skip (Integer): Number of records to skip (pagination)
- Default: 0
- Example: 0, 10, 20
limit (Integer): Maximum number of records to return (pagination)
- Default: 10
- Example: 10, 25, 50
search_keyword (String): Search agents by keyword across multiple fields
- Searches in: first_name, last_name, email, dial_code, phone_number, account_number
- Example: "Mor", "Toure", "776497134"
start_date (Long): Filter agents created after this timestamp (epoch)
- Example: 1731697928
end_date (Long): Filter agents created before this timestamp (epoch)
- Example: 1757466632
filter (Integer): Agent type filter
- 1 = Specific agent type 1
- 2 = Specific agent type 2
- If not provided, searches all agent types

Headers

authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyNDc3N2I5ZDA3MmY0OWJiOGQzNjY0MjE2Mjg4MDVkMCIsInJvbGVzIjpbIlJPTEVfQUdFTlQiXSwiZXhwIjoxNzU3NTI1MjQxfQ.KlzfPocW-sPvxprUqwwiX5laJkQO-a4MAfrZo-1XqgA
companyid: 59388167894b4d10a04fe5da3b8a2104
requestid: b35d332f-131e-44c1-892f-8322e022da74

Response

{
    "success": 1,
    "error": [],
    "data": {
        "users": [
            {
                "id": "4bc80d0702674d81aef2405bfbd3794e",
                "first_name": "Mor Toure",
                "last_name": "THIAM",
                "email": "Papethiam@smk.sn",
                "dial_code": "+221",
                "phone_number": "776497134",
                "user_type": 5,
                "role_id": "null",
                "account_number": "1731697928045",
                "verification": {
                    "is_email": false,
                    "is_phone": true
                },
                "birth_date": 202608000,
                "image": "",
                "user_code": "AGT_H778ZT96",
                "country_id": "98bb46292cb04a258805f56708f1cabf",
                "status_id": 1,
                "kyc_status": 1,
                "kyc_process_status": 1,
                "location_point": {
                    "type": "Point",
                    "coordinates": [
                        -17.4716024,
                        14.7225055
                    ]
                },
                "rating": null,
                "created_date": 1731697928,
                "parent_user_id": "null",
                "display_name": "null",
                "kyc_status_id": null,
                "address_info": {},
                "updated_date": null,
                "display_image": null,
                "reason_code_id": null,
                "reject_reason": null,
                "unique_device_id": null
            },
            {
                "id": "1a849243f9274684b3bd8c5e8c279d78",
                "first_name": "OUSMANE",
                "last_name": "KHOULÉ",
                "email": "khouleousmane.ok@gmail.com",
                "dial_code": "+221",
                "phone_number": "777303030",
                "user_type": 5,
                "role_id": "null",
                "account_number": "1721251910039",
                "verification": {
                    "is_email": false,
                    "is_phone": true
                },
                "birth_date": 1153679400000,
                "image": "",
                "user_code": "AGT_MKPE8MZI",
                "country_id": "1a5518d166cb4a3c8231f74d917cdac3",
                "status_id": 1,
                "kyc_status": 2,
                "kyc_process_status": 4,
                "location_point": {
                    "type": "Point",
                    "coordinates": [
                        -17.4676861,
                        14.716677
                    ]
                },
                "rating": null,
                "created_date": 1721251910,
                "parent_user_id": "null",
                "display_name": "null",
                "kyc_status_id": null,
                "address_info": {},
                "updated_date": null,
                "display_image": null,
                "reason_code_id": null,
                "reject_reason": null,
                "unique_device_id": null
            }
        ]
    }
}

Response Fields

success (integer): Response status indicator
- 1 = Success
- 0 = Failure
error (array): Array of error messages (empty on success)
data (object): Response data object
- users (array): Array of nearby agent objects

Agent Object Fields

id (string): Agent primary ID
first_name (string): Agent's first name
last_name (string): Agent's last name
email (string|null): Agent's email address
dial_code (string): Country dial code
phone_number (string): Phone number
user_type (integer): Always 5 for agents
role_id (string|null): Agent's role ID
account_number (string): Agent's account number
verification (object): Verification status object
- is_email (boolean): Email verification status
- is_phone (boolean): Phone verification status
birth_date (long): Agent's birth date (epoch timestamp)
image (string): Agent's profile image URL
user_code (string): Unique agent code (format: AGT_XXXXXXXX)
country_id (string): Country ID
status_id (integer): Agent status ID (see Constants for values)
kyc_status (integer): KYC status (see Constants for values)
kyc_process_status (integer): KYC process status (see Constants for values)
location_point (object): Agent's geographical location
- type (string): Always "Point" for GeoJSON Point
- coordinates (array): [longitude, latitude] coordinates
rating (number|null): Agent rating (if available)
created_date (long): Agent account creation timestamp
parent_user_id (string|null): Parent user ID
display_name (string|null): Display name
kyc_status_id (string|null): KYC status ID
address_info (object): Address information object
updated_date (long|null): Last update timestamp
display_image (string|null): Display image URL
reason_code_id (string|null): Reason code ID
reject_reason (string|null): Rejection reason
unique_device_id (string|null): Unique device identifier

Example Usage

Basic Request

curl --location 'https://api.gafapay.com:8443/gafapay/v3/user/get_nearby_agents?latitude=14.733333333333333&longitude=-17.633333&radius=1000000' \
--header 'authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyNDc3N2I5ZDA3MmY0OWJiOGQzNjY0MjE2Mjg4MDVkMCIsInJvbGVzIjpbIlJPTEVfQUdFTlQiXSwiZXhwIjoxNzU3NTI1MjQxfQ.KlzfPocW-sPvxprUqwwiX5laJkQO-a4MAfrZo-1XqgA' \
--header 'companyid: 59388167894b4d10a04fe5da3b8a2104' \
--header 'requestid: b35d332f-131e-44c1-892f-8322e022da74'

Request with Pagination

curl --location 'https://api.gafapay.com:8443/gafapay/v3/user/get_nearby_agents?latitude=14.733333333333333&longitude=-17.633333&radius=1000000&skip=0&limit=5' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID'

Request with Search Keyword

curl --location 'https://api.gafapay.com:8443/gafapay/v3/user/get_nearby_agents?latitude=14.733333333333333&longitude=-17.633333&radius=1000000&search_keyword=Mor' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID'

Request with Agent Type Filter

curl --location 'https://api.gafapay.com:8443/gafapay/v3/user/get_nearby_agents?latitude=14.733333333333333&longitude=-17.633333&radius=1000000&filter=1' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID'

Notes

Geospatial Search: This API uses MongoDB's geospatial capabilities to find agents within the specified radius
Distance Calculation: The radius parameter is in meters and uses spherical distance calculations
Agent Type: All returned users have user_type: 5 (Agent)
Location Format: Agent locations are stored as GeoJSON Point objects with [longitude, latitude] coordinates
Search Keyword: The search functionality looks across multiple fields including name, email, and phone number
Pagination: Use skip and limit parameters for pagination when dealing with large result sets
Performance: A 2dsphere index is required on the location_point field for optimal performance

Overview​

API Details​

Endpoint​

Query Parameters​

Required Parameters​

Optional Parameters​

Headers​

Response​

Response Fields​

Agent Object Fields​

Example Usage​

Basic Request​

Request with Pagination​

Request with Search Keyword​

Request with Agent Type Filter​

Notes​

Overview

API Details

Endpoint

Query Parameters

Required Parameters

Optional Parameters

Headers

Response

Response Fields

Agent Object Fields

Example Usage

Basic Request

Request with Pagination

Request with Search Keyword

Request with Agent Type Filter

Notes