Looking to integrate Real-time GPS Tracking capability to your Business Application? Close-Guard Technology got you covered!
Contents
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-12-08 02:56:04", "last_heartbeat": "2024-12-08 02:56:04" } }
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-12-08 02:56:04) |
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-12-08 02:56:04", "last_heartbeat": "2024-12-08 02:56:04" }, { "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-12-08 02:56:04", "last_heartbeat": "2024-12-08 02:56:04" } ] }
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", "lavel": "BMW Z420", "type": "Car", "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-12-08 02:56:04", "last_heartbeat": "2024-12-08 02:56:04", "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-12-08 02:56:04", } }
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" }