Overview

Close-Guard GPS Tracking API is designed for developers to easily and seamlesly integrate Real-time GPS tracking functionality on any application using any software programing technology or development platform

The API allow you to programmatically interact with Close-Guard GPS tracking devices and services such as

Our API attempts to conform to the RESTful design principles. You interact with the resources exposed through the API by accessing resource collection and element URIs using the HTTP POST.

You will likely need access to a web developer or programmer (if you’re not one) to get the most use out of Close-Guard API.

Access to Close-Guard GPS tracking API is Freely available to all Close-Guard Technology customers

Requirements

In order to interact with Close-Guard GPS Tracking API, you must fulfil all of the following requirements;

You can get a Close-Guard customer account (If you haven't got one already) by purchasing any of our GPS tracing devices from us or authorized dealer See our authorized dealers

Once you have setup an account, simply Login to Close-Guard Client Portal, navigate to Developers from the main menu to enable API access on your account and access your API credentials

URL

Close-Guard GPS tracking API URL is made up of the base URL, the resource URI and an API key. A complete API URL will look like this; https://api.closeguardtechnology.com/v1/‹API Key›/‹resource URI›

Test Credentials

The following API credentials can be use to interact with Close-Guard API for evaluation purposes only;

API Key: 396slbHG7506Rlglhglbfj7
API Token: 3853925hxnsvdebdyh36s
Device IMEI: 153865863307200

Please note that these test credentials resets every Sunday night

Authentication

All requests to Close-Guard API requires authentication. Our API Authentication is implemented as HTTP Header Authentication over TLS (HTTPS).

To authenticate your request, you need to pass the following parameters as part of your HTTP request headers;

Api-Token: Your account API token
Request-Id: A unique identifier of your current request (must be unique for each request)

Sample Authentication using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/devicelist' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
                

Request Method

Close-Guard API accept only form encoded HTTP POST requests. Any other request method will not be recognized by our API

Request Limits

Access to our API is completely Free. However, a limit of 10 inbound API requests per minute applies. This simply means you can only make up to 10 calls per device to our API every minute. Requests sent from our server to your callback URL does not count.

If you need to exceed our API request limit, please Contact Us so we can discus your requirements.

Response Format

Close-Guard API response (success or error) is returned in JSON data. Response codes are sent via the normal HTTP Response Code,

Sample Success Response

{
    "request": "devicelist",
    "status":"success",
    "data":{
            "id": "123",
            "sim_number": "234812345678",
            "imei": "123456789012345",
            "last_longitude": "9.14562",
            "last_latitude": "7.62862",
            "last_speed": "44.50",
            "last_altitude": "440",
            "last_status": "Ignition On",
            "last_track_time": "2024-04-26 13:12:57",
            "last_heartbeat": "2024-04-26 13:12:57"
          }
}           	
                

Sample Error Response

{
    "request":"devicelist",
    "status":"error",
    "message":"No devices found"
}
                

POST - Create New Device /create

This API allows you to create and activate a new GPS device on Close-Guard.

Request Parameters

Parameter	Description
imei Required	A valid Close-Guard GPS device IMEI. This is usually written om the GPS Device
license Required	License Plate Number of the vehicle or any other Unique identifier for the device (Example: AA-123-BBB)
admin_contact1 Required	Your preferred device admin contact phone number, including country code (Example: 2348031234567)
tracker_phone_number Required	Phone number of the SIM card inserted in the GPS device, including country code (Example: 2348091234567)
operator Required	Network provider of the SIM card inserted in the GPS device. Accepted values are 9mobile, MTN, Glo or Airtel

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/create' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'imei=1234567890123&admin_contact1=23480123456788&tracker_phone_number=2348091234567&operator=9mobile'
                

Sample Success Response

{
    "request":"create",
    "status":"success",
    "message":"Device registration successful",
    "device_id":"1234"
}
                

POST - Real-Time Location Callback

Close-Guard API always push GPS location data from all your active devices in real-time to the Callback URL you you specified for your account using HTTP POST.

To use this feature, you must set a valid callback URL on your account. To do this, Login to your account at Close-Guard portal, then navigate to Developers on the main menu and set your desired callback URL and POST Encoding

Please note that our API will only POST to your callback URL when the position or status of any of your active devices change and will never send more than one request to your callback URL every 5 seconds. In case you need the longitude and latitude reversed, include query string "reverse_longlat" in your callback URL

POST Parameters

The following parameters are POSTed to your callback URL in JSON or Form data encoded format, depending on your callback setting;

Parameter	Description
id (string)	The GPD device unique system ID
imei (string)	The GPS device IMEI
longitude (string)	The current longitude of the GPS device in decimal degrees (example: 7.49508)
latitude (string)	The current Latitude of the GPS device in decimal degrees (example: 9.05785)
speed (string)	The current speed of the GPS device in Km/h (if in motion)
altitude (string)	The current altitude of the GPS device in meters above sea level (if available)
status (string)	The current status of the GPS device. Possible values are: Battery Disconnect Alert, Tracker Power Cut-off Alert, Low Battery Alert, Vibration Alert, Ignition On Alert, Over Speed Alert or No Alarm Please note that we may add new status at anytime
track_time (string)	The current date and time (example: 2024-04-26 13:12:57)

Sample callback POST data in JSON format

{
    "id":"3",
    "imei":"143345456643455",
    "longitude":"1.23456",
    "latitude":"2.34567",
    "speed":"0",
    "altitude":"378",
    "status":"Battery Disconnect Alert",
    "track_time":"2020-12-02 11:15:22"
}
                

Sample Script to retrieve POST data using PHP

You can use the following sample PHP script to capture data POSTed from our API server on your callback script assuming your callback is configured to use Form Encoded Data

‹?php
    //Verify valid data has been sent to the callback URL
    if(isset($_POST['imei'])&&!empty($_POST['longitude'])&&!empty($_POST['latitude'])) {
        foreach ($_POST as $parameter => $value ){ //Loop through all POST fields to get values
	        ${$parameter} = $value;
	    }
        $device_id = $id;
        $device_imei = $imei;
        $current_longitude = $longitude;
        $current_latitude = $latitude;
        $current_speed = $speed;
        $current_altitude = $altitude;
        $current_status = $status;
        $tracking_data_time = $track_time;
        /*
          You can then save the data in your database or render it in other ways.
        */
    }
?›
                

POST - Fetch Device List /devicelist

This API allows you to fetch the list of all your Close-Guard GPS devices.

Request Parameters

Parameter	Description
limit Optional	Maximum number of devices to return. Setting this parameter to 0 or not passing a value will return all devices

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/devicelist' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'limit=0'
                

Sample Success Response

{
    "request": "devicelist",
    "status":"success",
    "data":[
            {"id": "123",
            "sim_number": "234812345678",
            "imei": "123456789012345",
            "last_longitude": "9.14562",
            "last_latitude": "7.62862",
            "last_speed": "44.50",
            "last_altitude": "440",
            "last_status": "Ignition On",
            "last_track_time": "2024-04-26 13:12:57",
            "last_heartbeat": "2024-04-26 13:12:57"
          },
          {
            "id": "124",
            "sim_number": "234803333678",
            "imei": "98765432162338",
            "last_longitude": "9.40311",
            "last_latitude": "7.84155",
            "last_speed": "0.00",
            "last_altitude": "440",
            "last_status": "No Alarm",
            "last_track_time": "2024-04-26 13:12:57",
            "last_heartbeat": "2024-04-26 13:12:57"
          }
    ]
}           	
                

POST - Single Device Information /deviceinfo

This API allows you to fetch details of a GPS device using the IMEI.

Request Parameters

Parameter	Description
device_imei Required	A valid Close-Guard GPS device IMEI

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/deviceinfo' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'device_imei=1234567890123'
                

Sample Success Response

{
    "request": "deviceinfo",
    "status":"success",
    "data":{
            "id": "123",
            "imei": "1234567890123",
            "sim_number": "2347034444444",
            "sim_operator": "MTN",
            "last_longitude": "9.12345",
            "last_latitude": "7.12345",
            "last_speed": "32.10",
            "last_altitude": "440",
            "fuel_level": "63",
            "last_status": "No Alarms",
            "last_track_time": "2024-04-26 13:12:57",
            "last_heartbeat": "2024-04-26 13:12:57",
            "admin_contact1": "2348012345678",
            "admin_contact2": "",
            "admin_contact3": "",
            "power_cut_alarm_status": "0",
            "ignition_alarm_status": "0",
            "vibration_alarm_status": "0",
            "overspeed_alarm_status": "1",
            "speed_limit": "80",
            "geo_fence_status": "0",
            "demobilizer_status": "0"
	}
}                
    

POST - Get Device Last Location /locate

This API allows you to get the last location of a GPS device on Close-Guard using the IMEI

Request Parameters

Parameter	Description
device_imei Required	A valid Close-Guard GPS device IMEI

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/locate' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'device_imei=123456789012345'
                

Sample Success Response

{
    "request": "locate",
    "status":"success",
    "data":{
            "id": "123",
            "imei": "123456789012345",
            "last_longitude": "9.14562",
            "last_latitude": "7.62862",
            "last_speed": "44.50",
            "last_altitude": "440",
            "last_status": "Ignition On",
            "last_track_time": "2024-04-26 13:12:57",
    }
}             
                

POST - Update Device Status /updatestatus

This API allows you to update one or more status of a GPS device on Close-Guard.

Request Parameters

Parameter	Description
device_imei Required	A valid Close-Guard GPS device IMEI
power_cut_alarm_status Optional	Set this parameter to 1 to enable alert when external power is disconnected from the device. Any other value will disable the alert.
ignition_alarm_status Optional	Set this parameter to 1 to enable alert when the ignition is turned on for compatible device. Any other value will disable the alert.
vibration_alarm_status Optional	Set this parameter to 1 to enable alert when the device is vibrated. Any other value will disable the alert.
overspeed_alarm_status Optional	Set this parameter to 1 to enable alert when the speed of the device exceeds the set speed limit for it. Any other value will disable the alert.
geo_fence Optional	Set this parameter to 1 to set Geo-Fence on the device using its current location. Any other value will cancel the fence.
mobilization_status Optional	Set this parameter to 1 to send demobilize command to the device. Any other value will cancel the command and restore normal operation.

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/updatestatus' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'device_imei=1234567890123&power_cut_alarm_status=1&ignition_alarm_status=0'
                

Sample Success Response

{
    "request":"updatestatus",
    "status":"success",
    "message":"Device information update successful"
}
                

POST - Update Device Information /updateinfo

This API allows you to update one or more information of a GPS device on Close-Guard.

Note: Any invalid parameter value will be ignored and not updated!

Request Parameters

Parameter	Description
device_imei Required	A valid Close-Guard GPS device IMEI
notify_number1 Optional	The Device Primary Admin Contact Number: Set this parameter to a valid mobile number to update the device primary admin number
notify_number2 Optional	The Device Admin Contact Number 2: Set this parameter to a valid mobile number to update the device admin 2 number
notify_number3 Optional	The Device Admin Contact Number 3: Set this parameter to a valid mobile number to update the device admin 3 number
operator Optional	The Device SIM Network Operator: Set this parameter to a valid local network operator to update the device SIM network. Accepted values are 9mobile, MTN, Glo or Airtel
phone Optional	The Device SIM number: Set this parameter to a valid mobile number to update the device SIM number
fence_radus Optional	Geo-Fence Radius: Set this to a numerical value between 10 - 10,000 to update the fence radius of the device in Kilometers
speed_limit Optional	Device Speed Limit: Set this to a numerical value between 20 - 200 to update device max. speed limit in Km/h
license Optional	Vehicle License Number (any string is allowed)
engine_type Optional	Vehicle Engine Type: Set this to a valid vehicle engine capacity to update the engine capacity of the vehicle (e.g. 3.0, 2.7, 4.0, etc)
fuel_tank Optional	Vehicle Fuel Tan Capacity: Set this parameter to any numeric value between 0 - 250 to update the fuel tank capacity in Lit res
new_password Optional	Device New Password: Set this parameter to any 6 digits number to update the GPS device password

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/updateinfo' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'device_imei=1234567890123&admin_contact1=23480123456788'
                

Sample Success Response

{
    "request":"updateinfo",
    "status":"success",
    "message":"Device information update successful"
}                

POST - Reboot Device /reboot

This API allows you to send Reboot command to a GPS device on Close-Guard.

Request Parameters

Parameter	Description
device_imei Required	A valid Close-Guard GPS device IMEI

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/reboot' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'device_imei=1234567890123'
                

Sample Success Response

{
    "request":"reboot",
    "status":"success",
    "message":"Device reboot successful"
}                

POST - Reset Device /reset

This API allows you to send Factory Reset command to a GPS device on Close-Guard.

Request Parameters

Parameter	Description
device_imei Required	A valid Close-Guard GPS device IMEI

Sample Request using CURL

   curl --request POST \
     --url 'https://api.closeguardtechnology.com/v1/396slbHG7506Rlglhglbfj7/reset' \
     --header 'Api-Token: 3853925hxnsvdebdyh36s' \
     --header 'Request-Id: 123456789' \
     --header 'content-type: application/x-www-form-urlencoded'
     --data 'device_imei=1234567890123'
                

Sample Success Response

{
    "request":"reset",
    "status":"success",
    "message":"Device reset successful"
}