Home -  Baza wiedzy -  API IKOL

API IKOL

Platforma ikol bezpłatnie udostępnia klucze API dla developerów tworzących aplikacje ogólnodostępne dla wszystkich użytkowników ikol.

Communication parties

There are two communication parties:

  • ikol API service used as a server (referred to as System)
  • Customer information system (referred to as Customer).
The active party is Customer, who sends requests to System and waits for a response.
API is accessed via URL below:
https://api.ikol.pl/functionName?parameter1=value1&param2=value2&...

Response time

All requests are processed immediately unless specified otherwise.

Operation description

API is accessed via secure connection (SSL/HTTPS), no additional client certificates are required.
All the requests require script execution (function name is the script name) and parameters are sent via GET or POST. Response is provided either in XML (default) or JSON format.

Character encoding

All data sent in parameters must be encoded as UTF-8 and sent according to the http protocol rules (urlencode). Likewise ikol API returns all data UTF-8 encoded.

Auhentication

For most of the API functions there are two ways of authenticating a request:

  1. By providing login and password for each API request. This method is recommended for server-server applications that do not require user authentication on the Customer side.
  2. By getting session id and providing it for each API request. This method is preferred one and is strongly recommended for all client-server applications. In order to start a user session iaLoginSession function should be used. For terminating a user session iaLogoutSession function should be used.

Query limitations

System may limit number of allowed requests per user, account or locator. If the limit is reached error code is return as a result of the function. Customer system should be designed according to ikol API limitation rules.

Limits may apply to:

  • account – global limit for all users and locators of an account
  • locator – limit for requests regarding a locator
  • user – limit for requests from a user
For example if for a function iaGetLocatorOdometer applies a limit of 1 request per locator per 1 minute it means that this function will return a valid response once every minute for each locator. If there are 3 locators assigned to the account, this function is allowed to be run 3 times every minute for each locator or once requesting odometer value for all 3 locators.

Locator API keys

Customer system references to a locator using locator API key. Default locator API key is the locator number but it may be changed to fit specific customer needs (i.e. it may be the primary key of the vehicle in Customer’s system) as long as it is unique.
API requests limit requested api keys to 5 per request.

User privileges

Account administrator is allowed to create new users and grant them different privileges. User that is used to access ikol API must be granted API privilege to all locators to which Customer system needs to have access via API.

Functions

iaGetApiVersion

Function returns API system version basic information

Query example:

 https://api.ikol.pl/iaGetAPIVersion?login=user&password=pass&output=json
 https://api.ikol.pl/iaGetAPIVersion?sid=rokm0290p8qvgke2d5114df85&output=json

Default limitations:
1 request per account per 5 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
output[xml|json]Output format
Output example (JSON):

 {
 	"version":{
		 "author": "ikol",
 	"version": "1.1",
	 "development": "stable"
	 },
 "result": 0,
 "resultdesc": "OK"
 }
Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
resultdescStringResult description
versionObjectVersion object
version.authorStringAPI author
version.versionStringAPI version and subversion
version.developmentStringDevelopment status of this API version

iaLoginSession

Function starts new user session and returns session identifier

Query example:

 https://api.ikol.pl/iaLoginSession?login=user&password=pass&output=json
 https://api.ikol.pl/iaLoginSession?login=user&password=pass&appkey=nHgdYtdg54&gcm_id=bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1&gcm_stat=1&output=json

Default limitations:
No limitations

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API acces to at least one of the customer’s locators
passwordStringUser password
appkeyStringApplication API key (parameter used only for ikol certified applications that require application level API key)
gcm_idStringOptional parameter that represents GCM id
gcm_statIntegerWhen GCM status is set to 1 application will receive standard alert messages from the system, if GCM status is set to 0 system will ignore this session and will not send GCM messages
versionStringApplication version (optional parameter that provides version of the application that logs in a user)
output[xml|json]Output format
Output example (JSON):

 {
	"sid": "dm7m0290p8qvgke2d5114df851",
	"user": {
		"name": "Roger",
		"last_name": "Gordon"
	},
	"result": "0",
	"resultdesc": "OK"
}
Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
resultdescStringResult description
userObjectUser object
user.nameStringName of the logged user
user.last_nameStringLast name of the logged user
sidStringSession identifier

iaLogoutSession

Function terminates existing user session

Query example:

 https://api.ikol.pl/iaLogoutSession?sid=lv28abstf5313k7ss5gp9jefa6&output=json

Default limitations:
No limitations

Query parameterFormatDescription
sidStringSession identifier
output[xml|json]Output format
Output example (JSON):

 {
	"result": "0",
	"resultdesc": "OK"
 }
Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
resultdescStringResult description

iaGetUserLocators

Function returns list of user’s locators

Query example:

 https://api.ikol.pl/iaGetUserLocators?login=user&password=pass&output=json
 https://api.ikol.pl/iaGetUserLocators?sid=rokm0290p8qvgke2d5114df85&access_rights=DSPLY&output=json

Default limitations:
1 request per user per 300 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
access_rightsStringName of the access right to the locator:

  • DSPLY – User right that grants access to locator’s live position and track history
  • VHCFG – User right that grants access to locator’s personalization configuration (such as label or icon)
  • VHADM – User right that grants access to locator’s locator administration (such as ignition starter control)
  • ALERT – User right that grants access to locator’s alert configuration
  • ARPRT – User right that grants access to locator’s advanced configuration (such as widgets, atuomatic reports)
  • TTYPE – User right that grants access to locator’s reports modification (such as business/private trips)
  • IKSRV – User right that grants access to locator’s services configuration
  • IKAPI – User right that grants access to locator through API

Default value of this parameter is DSPLY.

output[xml|json]Output format
Output example (JSON):

 {
	"locators": [{
		"group": {
			"name": "Test locators",
			"order": "1",
			"default_open": "1"
		},
		"generalinfo": {
			"key": "apikey1",
			"id": "868789020145498",
			"platform": "V"
		},
		"display": {
			"label": "CC9827A",
			"icon": "http://dev1.ikol.pl/graphics/icons/maps/v/carsmpy.png"
		},
		"vehicle": {
			"make": "Mercedes",
			"model": "SPRINTER",
			"plateid": "CC9827A",
			"vin": "993477388288222"
		},
		"users": {
			"mainuser": "Roger Bond"
		}
	},
	{
		"group": {
			"name": "Test locators",
			"order": "1",
			"default_open": "1"
		},
		"generalinfo": {
			"key": "apikey2",
			"id": "862170014709487",
			"platform": "V"
		},
		"display": {
			"label": "John Wright",
			"icon": "http://dev1.ikol.pl/graphics/icons/maps/v/carsmpb.png"
		},
		"vehicle": {
			"make": "Honda",
			"model": "ACCORD",
			"plateid": "X0PLATE",
			"vin": "ABC123456789ABCDEH"
		},
		"users": {
			"mainuser": "Ann Frost"
		}
	},
	{
		"group": {
			"name": "Private locators",
			"order": "2",
			"default_open": "0"
		},
		"generalinfo": {
			"key": "apikey3",
			"id": "860599000023472",
			"platform": "P"
		},
		"display": {
			"label": "ikol SPOT",
			"icon": "http://dev1.ikol.pl/graphics/icons/maps/v/carpckr.png"
		},
		"users": {
			"mainuser": "Rex"
		}
	}],
	"result": "0",
	"resultdesc": "OK"
}
Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 5 – API request limit has been reached
resultdescStringResult description
locatorsArray of ObjectsArray of user locators
locators[n].groupObjectObject of locator’s group
locators[n].group.nameStringGroup name
locators[n].group.orderIntegerGroup order index
locators[n].group.default_open[0|1]Indicates whether locator’s group is open or closed by default:

  • 0 – Group is closed by default
  • 1 – Group is open by default
locators[n].generalinfoObjectObject of locator general information
locators[n].generalinfo.keyStringLocator API key
locators[n].generalinfo.idStringLocator unique identifier
locators[n].generalinfo.platformChar[1]Locator mobility platform:

  • V – vehicle powered locator
  • P – portable locator
  • M – mobile locator (ikol x platform)
locators[n].displayObjectObject of locator display information
locators[n].display.labelStringLocator display label
locators[n].display.iconStringURL of the icon assigned to the locator
locators[n].usersObjectObject of locator user assignments
locators[n].users.mainuserStringLocator main user name
locators[n].vehicleObjectIf locator’s platform is Vehicle this object contains vehicle information
locators[n].vehicle.makeStringVehicle make
locators[n].vehicle.modelStringVehicle model
locators[n].vehicle.plateidStringVehicle plate number (registration number)
locators[n].vehicle.vinStringVehicle identification number (VIN)
locators[n].deviceObjectIf locator’s platform is Mobile this object contains mobile device information
locators[n].device.nameStringName of the type of the device
locators[n].device.makeStringDevice make

iaGetUserInformation

Function returns information about specified user. If no user parameters are specified, function returns current user information.

Query example:

 https://api.ikol.pl/iaGetUserInformation?login=user&password=pass&output=json
 https://api.ikol.pl/iaGetUserInformation?sid=rokm0290p8qvgke2d5114df85&key=kayne@example.com,lynch@example.com&output=json

Default limitations:
No limits

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated users logins
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time
Output example (JSON):

{
    "users": {
        "kayne@example.com": {
            "login": "kayne@example.com",
            "name": "Kayne",
            "surname": "",
            "email": "kayne@example.com",
            "phone": "",
            "activitydate": 20170105145125,
            "picture": "https://storage.ikol.pl/data/us/pics/Xmt7WNCdWO48jgI/picture_100.jpg",
            "stat": 0,
            "statdesc": "OK"
        },
        "lynch@example.com": {
            "login": "lynch@example.com",
            "name": "Lynch",
            "surname": "",
            "email": "lynch@example.com",
            "phone": "",
            "activitydate": 20170105131155,
            "picture": "https://storage.ikol.pl/data/us/pics/Xmt7WNCdWO48jgI/picture_100.jpg",
            "stat": 0,
            "statdesc": "OK"
        }
    },
    "result": 0,
    "resultdesc": "OK"
}
Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 5 – API request limit has been reached
resultdescStringResult description
usersArray of ObjectsArray of users where email stands for key.
When XML output is selected, email `key tag`
is stripped from any characters that are not:

  • letters
  • whole numbers
  • sign `_`
users.key.loginStringUser login
users.key.nameStringUser name
users.key.surnameStringUser surname
users.key.emailStringUser email
users.key.phoneStringUser phone
users.key.activitydateYYYYmmddHHiissLast user activity (last login)
users.key.pictureStringUser picture
users.key.statIntegerStatus
users.key.statdescStringUser status description

iaGetLocatorTripDaysOfMonth

Function returns days of given year and month where at least one trip for given locators have existed.

Query example:

 https://api.ikol.pl/iaGetLocatorTripDaysOfMonth?login=user&password=pass&key=vehicle12345,locator67890&timezone=utc&date=201701&output=json
 https://api.ikol.pl/iaGetLocatorTripDaysOfMonth?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&timezone=utc&date=201701&output=json
Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
dateStringYear and month passed as string. example: 201701
Passed year: 2017
Passed month: 01
This parameter is not mandatory. If empty, current month will be used.
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time both as an input and a result
Output example (JSON):

{
    "days": ["03", "10", "01", "02", "04", "05", "06", "07", "08", "09", "11", "12", "13"],
    "result": 0,
    "resultdesc": "OK"
}
Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
resultdescStringResult description
statIntegerNumerical code of a query status for given locators:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
  • 4 – Contract does not have track service enabled
  • 5 – Request exceeds available position history depth for this contract
statdescStringQuery status description for given locators.
daysArray Of StringArray of days represented as two-character string.

iaGetLocatorOdometer

Function returns locator most recent odometer readings from both internal GPS counter and CAN/OBD readings if available

Query example:

 https://api.ikol.pl/iaGetLocatorOdometer?login=user&password=pass&key=vehicle12345,locator67890&output=json
 https://api.ikol.pl/iaGetLocatorOdometer?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&output=json

Default limitations:
1 request per locator per 60 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time
Output example (JSON):

 {
 	"locator": {
 		"vehicle12345": {
 			"request": {
 				"stat": 0,
 				"statdesc": "OK"
 			},
 			"odometer": {
 				"value": 5268.5,
 				"timestamp": "20130103184215",
 				"valuecan": 65165,
 				"timestampcan": "20130103214153"
 			}
 		},
 		"locator67890": {
 			"request": {
 				"stat": 0,
 				"statdesc": "OK"
 			},
 			"odometer": {
 				"value": 8274.1,
 				"timestamp": "20130103184115"
 			}
 		}
 	},
 	"result": 0,
 	"resultdesc": "OK"
 }

Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
locator.key.request.statdescStringLocator object status description
locator.key.odometerObjectObject of locator odometer readouts
locator.key.odometer.valueDoubleLocator internal odometer value in km
locator.key.odometer.timestampYYYYmmddHHiissDate and time of the odometer readout
locator.key.odometer.valuecanDoubleOdometer value in km retrieved from the CAN bus of the vehicle
locator.key.odometer.timestampcanYYYYmmddHHiissDate and time of the odometer readout from CAN bus of the vehicle

iaGetLocatorInformation

Function returns information about locator

Query example:

 https://api.ikol.pl/iaGetLocatorInformation?login=user&password=pass&key=vehicle12345,locator67890&output=json
 https://api.ikol.pl/iaGetLocatorInformation?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&output=json

Default limitations:
1 request per locator per 300 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
output[xml|json]Output format
Output example (JSON):

 {
	"locator": {
		"vehicle12345": {
			"request": {
				"stat": "0",
				"statdesc": "OK"
			},
			"generalinfo": {
				"id": "513286020469756",
				"hardware": "ikol Go",
				"platform": "V"
			},
			"display": {
				"label": "Ford Jimmy",
				"icon": "http://system.ikol.pl/graphics/icons/maps/v/carmanb.png"
			},
			"vehicle": {
				"make": "Ford",
				"model": "Focus",
				"plateid": "XT63527",
				"vin": "VMFD251RADJ009851"
			},
			"users": {
				"mainuser": "Jimmy Logan"
			}
		},
		"locator67890": {
			"request": {
				"stat": "0",
				"statdesc": "OK"
			},
			"generalinfo": {
				"id": "358853052175754",
				"hardware": "ikol X Android",
				"platform": "M"
			},
			"display": {
				"label": "Marry Samsung",
				"icon": "http://system.ikol.pl/graphics/icons/maps/v/carwomr.png"
			},
			"device": {
				"name": "SMARTFON",
				"make": "SAMSUNG"
			},
			"users": {
				"mainuser": "Marry Logan"
			}
		}
	},
	"result": "0",
	"resultdesc": "OK"
}
Query parameterFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
locator.key.request.statdescStringLocator object status description
locator.key.generalinfoObjectObject of locator general information
locator.key.generalinfo.idStringLocator unique identifier
locator.key.generalinfo.hardwareStringVersion of locator hardware
locator.key.generalinfo.platformChar[1]Locator mobility platform:

  • V – vehicle powered locator
  • P – portable locator
  • M – mobile locator (ikol x platform)
locator.key.displayObjectObject of locator display information
locator.key.display.labelStringLocator display label
locator.key.display.iconStringURL of the icon assigned to the locator
locator.key.usersObjectObject of locator user assignments
locator.key.users.mainuserStringLocator main user name
locator.key.vehicleObjectIf locator’s platform is Vehicle this object contains vehicle information
locator.key.vehicle.makeStringVehicle make
locator.key.vehicle.modelStringVehicle model
locator.key.vehicle.plateidStringVehicle plate number (registration number)
locator.key.vehicle.vinStringVehicle identification number (VIN)
locator.key.deviceObjectIf locator’s platform is Mobile this object contains mobile device information
locator.key.device.nameStringName of the type of the device
locator.key.device.makeStringDevice make

iaGetLocatorTrips

Function returns locator trip data from the selected date span

Query example:

 https://api.ikol.pl/iaGetLocatorTrips?login=user&password=pass&key=vehicle12345,locator67890&starttime=20120101000000&stoptime=20120102235959&timezone=utc&output=json
 https://api.ikol.pl/iaGetLocatorTrips?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&starttime=20120101000000&stoptime=20120102235959&timezone=utc&output=json

Default limitations:
1 request per locator per 300 seconds
Date span of the requested report may not exceed 62 days

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
starttimeYYYYmmddHHiissString representing start of the requested trip report, default value is the beginning of the current day
stoptimeYYYYmmddHHiissString representing stop of the requested trip report, default value is the current time
route[false|true]Whether to attach encoded trip route
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time both as an input and a result
Output example (JSON):

{
 "locator": {
 "vehicle12345": {
 "request": {
 "stat": "0",
 "statdesc": "OK"
 },
 "trips": [{
 "journey": {
 "timestamp": "20110101182339",
 "distance": "16900",
 "duration": "1116",
 "geopoint": {
 "lat": "51.099517",
 "lng": "22.799573"
 },
 "usetype": "0",
 "fuelused": "0.81",
 "fuelconsumption": "4.79"
 },
 "attitude": {
 "overrpm": 0,
 "accel": 1,
 "brake": 3,
 "overspeed": 0,
 "turn": 0
 },
 "stop": {
 "timestamp": "20110101184215",
 "duration": "51423",
 "geopoint": {
 "lat": "51.099517",
 "lng": "22.799573"
 },
 "address": {
 "country": "Polska",
 "region": "mazowieckie",
 "city": "Janki",
 "street": "Akacjowa 32"
 },
 "point": {
 "name": "TOP SERVICE",
 "global": "0"
 }
 }
 },
 {
 "journey": {
 "timestamp": "20110101205918",
 "distance": "15700",
 "duration": "935",
 "geopoint": {
 "lat": "51.099517",
 "lng": "22.799573"
 },
 "usetype": "0",
 "route": "ktwxfBcwbgb@]qIlhLumE`oFd~D",
 "fuelused": "0.83",
 "fuelconsumption": "5.29"
 },
 "attitude": {
 "overrpm": 1,
 "accel": 0,
 "brake": 1,
 "overspeed": 0,
 "turn": 0
 },
 "stop": {
 "timestamp": "20110101211453",
 "duration": "-1",
 "geopoint": {
 "lat": "51.099517",
 "lng": "22.799573"
 },
 "address": {
 "country": "Polska",
 "region": "mazowieckie",
 "city": "Warszawa",
 "street": "Aleja Krakowska 48/52"
 },
 "point": {
 "name": "LOJACK S.A.",
 "global": "0"
 }
 }
 }
 ],
 "tripinfo": {
 "summary": {
 "journeydistance": "32600",
 "journeyduration": "2051",
 "stopduration": "98865",
 "totalfuelused": "1.64",
 "totalfuelconsumption": "5.03",
 "attitude": {
 "mask": "01f",
 "overspeed": "0",
 "overrpm": "1",
 "accel": "1",
 "brake": "4",
 "turn": "0"
 }
 },
 "count": "2"
 }
 },
 "ikolxewa": {
 "request": {
 "stat": "0",
 "statdesc": "OK"
 },
 "trips": [{
 "journey": {
 "timestamp": "20110101104820",
 "distance": "3822.325742607",
 "duration": "1508",
 "geopoint": {
 "lat": "52.099517",
 "lng": "20.799573"
 },
 "usetype": "0",
 "route": "eg}{bBcxy{f@yp@iFtn@alHthBwxUaSceLFK??}c@mb@yHrfD||Zo`HzxN|oG??xpQ{vNzzTolV|eQauMdmU}a@jwUtfq@h|yfmAtbGctBzpGluPziZvkg@zjh@chCnog@wOdtJgrB|wK|hSbgYfvf@tMhV`gF}~``Oggz@`iZwsGhkSm_MlqIydOjENjuMkYEA??",
 "fuelused": "",
 "fuelconsumption": ""
 },
 "stop": {
 "timestamp": "20110101111328",
 "duration": "891",
 "geopoint": {
 "lat": "52.099517",
 "lng": "20.799573"
 },
 "address": {
 "country": "",
 "region": "",
 "city": "",
 "street": ""
 },
 "point": {
 "name": "",
 "global": ""
 }
 }
 ],
 "tripinfo": {
 "summary": {
 "journeydistance": "50469",
 "journeyduration": "16555",
 "stopduration": "84361",
 "totalfuelused": "0",
 "totalfuelconsumption": "0",
 "attitude": {
 "mask": "01f",
 "overspeed": "0",
 "overrpm": "0",
 "accel": "0",
 "brake": "0",
 "turn": "0"
 }
 },
 "count": "1"
 }
 }
 },
 "result": "0",
 "resultdesc": "OK"
 }

Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
  • 7 – Time span of the requested report exceeds its limits
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
  • 4 – Contract does not have track service enabled
  • 5 – Request exceeds available position history depth for this contract
locator.key.request.statdescStringLocator object status description
locator.key.tripsArray of ObjectArray of trip objects
locator.key.trips[n].journeyObjectObject of trip movement information
locator.key.trips[n].journey.timestampYYYYmmddHHiissJourney start date and time
locator.key.trips[n].journey.distanceIntegerJourney distance in meters
locator.key.trips[n].journey.durationIntegerJourney duration in seconds. -1 is returned if the duration may not be provided
locator.key.trips[n].journey.geopointObjectObject of geo point of the trip start location
locator.key.trips[n].journey.geopoint.latDoubleLatitude of the trip start location
locator.key.trips[n].journey.geopoint.lngDoubleLongitude of the trip start location
locator.key.trips[n].journey.usetypeIntegerTrip type identifier:

  • 0 – undefined
  • 1 – private
  • 2 – business

Information is available if „private/business trips” service is enabled for this locator

locator.key.trips[n].journey.routeStringEncoded trip route (consult Encoded Polyline Algorithm Format)
locator.key.trips[n].journey.fuelusedDoubleFuel used during the trip in liters, information is available if „CAN support” service is enabled for this locator
locator.key.trips[n].journey.fuelconsumptionDoubleFuel consumption during the trip in liters per 100km, information is available if „CAN support” service is enabled for this locator
locator.key.trips[n].attitudeObjectObject of user driving attitudes
locator.key.trips[n].attitude.accelIntegerHarsh accelerations count
locator.key.trips[n].attitude.brakeIntegerHarsh brakes count
locator.key.trips[n].attitude.overrpmIntegerHigh engine RPM’s count
locator.key.trips[n].attitude.overspeedIntegerOverspeeds count
locator.key.trips[n].attitude.turnIntegerHarsh turns count
locator.key.trips[n].stopObjectObject of trip stop information
locator.key.trips[n].stop.timestampYYYYmmddHHiissJourney stop date and time
locator.key.trips[n].stop.durationIntegerStop duration in seconds. -1 is returned of the duration may not be provided.
locator.key.trips[n].stop.geopointObjectObject of geo point of the trip stop location
locator.key.trips[n].stop.geopoint.latDoubleLatitude of the trip stop location
locator.key.trips[n].stop.geopoint.lngDoubleLongitude of the trip stop location
locator.key.trips[n].stop.addressObjectObject of address data of the trip stop location, information is available if „Address decoding” service is enabled for this locator
locator.key.trips[n].stop.address.countryStringCountry of the stop location address
locator.key.trips[n].stop.address.regionStringRegion/District/State of the stop location address
locator.key.trips[n].stop.address.cityStringCity of the stop location address
locator.key.trips[n].stop.address.streetStringStreet of the stop location address
locator.key.trips[n].stop.pointObjectObject of point information of the trip stop location, information is available if „Geographical customer/point database” service is enabled for this locator
locator.key.trips[n].stop.point.nameStringName of the point/customer
locator.key.trips[n].stop.point.typeStringPoint type name
locator.key.trips[n].stop.point.globalStringPoint global status:

  • 0 – account specific point/customer
  • 1 – global point/customer
locator.key.tripinfoObjectObject of all requested trips summary
locator.key.tripinfo.countIntegerCount of all trips of the locator
locator.key.tripinfo.summaryObjectObject of summary data of the trips if at least one trip is returned
locator.key.tripinfo.summary.journeydistanceIntegerTotal trips distance in meters
locator.key.tripinfo.summary.journeydurationIntegerTotal trips duration in seconds
locator.key.tripinfo.summary.stopdurationIntegerTotal stops duration in seconds
locator.key.tripinfo.summary.totalfuelusedDoubleTotal fuel used in liters
locator.key.tripinfo.summary.totalfuelconsumptionDoubleTotal average fuel consumption in liters per 100km
locator.key.tripinfo.summary.attitudeObjectObject of summary data of the trip attitude exceptions
locator.key.tripinfo.summary.attitude.maskHexHexadecimal mask of the attitude exceptions available for the attitude object. LSB order:

  • 0 – harsh accelerations
  • 1 – harsh brakings
  • 2 – harsh turns
  • 3 – overspeeds
  • 4 – over RPMs
locator.key.tripinfo.summary.attitude.accelIntegerHarsh accelerations count
locator.key.tripinfo.summary.attitude.brakeIntegerHarsh braking count
locator.key.tripinfo.summary.attitude.turnIntegerHarsh turns count
locator.key.tripinfo.summary.attitude.overspeedIntegerOverspeeds count
locator.key.tripinfo.summary.attitude.overrpmIntegerHigh RPM count

iaGetLocatorLastTripDay

Function returns day during which locator had at least one trip

Query example:

 https://api.ikol.pl/iaGetLocatorLastTripDay?login=user&password=pass&key=vehicle12345,locator67890&threshold_time=20120101000000&output=json
 https://api.ikol.pl/iaGetLocatorLastTripDay?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&threshold_time=20120101000000&output=json

Default limitations:
1 request per locator per 300 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
threshold_timeYYYYmmddHHiissString representing threshold day in or before which trip day is looked for (dafault value is current day)
only_real1|0Whether only not ignored trips are taken into account
output[xml|json]Output format
Output example (JSON):

 {
	"locator": {
		"vehicle12345": {
			"request": {
				"stat": 0,
				"statdesc": "OK"
			},
			"day": "20161220"
		},
		"locator67890": {
			"request": {
				"stat": 0,
				"statdesc": "OK"
			},
			"day": "20161219"
		}
	},
	"result": 0,
	"resultdesc": "OK"
}

Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
  • 4 – Contract does not have track service enabled
  • 5 – Request exceeds available position history depth for this contract
locator.key.request.statdescStringLocator object status description
locator.key.dayYYYYmmddDate of the last trip before threshold_time. When no such day is found empty value is returned.

iaGetLocatorLastPosition

Function returns most recent locator position together with additional information regarding this reading

Query example:

 https://api.ikol.pl/iaGetLocatorLastPosition?login=user&password=pass&key=vehicle12345,locator67890&timezone=utc&output=json
 https://api.ikol.pl/iaGetLocatorLastPosition?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&timezone=utc&output=json

Default limitations:
1 request per locator per 60 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time both as an input and a result
Output example (JSON):

 {
     "locator": {
         "apikey1": {
             "request": {
                 "stat": "0",
                 "statdesc": "OK"
             },
             "position": {
                 "mask": "231",
                 "gps": {
                     "timestamp": "20150531140352",
                     "expired": "0",
                     "geopoint": {
                         "lat": "51.025617",
                         "lng": "16.886183"
                     },
                     "acquisition": "GPS",
                     "accuracy": "0",
                     "heading": {
                         "value": "128",
                         "dir": "SE"
                     },
                     "gpsfix": "0",
                     "speed": "0",
                     "speedlimit": "0"
                 },
                 "extra": {
                     "icon": "http://img.ikol.pl/graphics/icons/maps/v/carlugn_0_0_0_0_1_3_1_0.png"
                 },
                 "tech": {
                     "backupbattery": {
                         "level": "91",
                         "status": "0"
                     }
                 }
             }
         },
         "apikey2": {
             "request": {
                 "stat": "0",
                 "statdesc": "OK"
             },
             "position": {
                 "mask": "dfb",
                 "gps": {
                     "timestamp": "20150531142322",
                     "expired": "0",
                     "geopoint": {
                         "lat": "52.169508",
                         "lng": "20.938908"
                     },
                     "acquisition": "GPS",
                     "accuracy": "1",
                     "heading": {
                         "value": "27",
                         "dir": "NE"
                     },
                     "gpsfix": "1",
                     "speed": "0",
                     "speedlimit": "0",
                     "altitude": "107.6"
                 },
                 "extra": {
                     "icon": "http://img.ikol.pl/graphics/icons/maps/v/cartrkr_0_0_0_0_1_3_0_0.png",
                     "driver": {
                         "name": "Michau0142 Kowalski",
                         "ibutton": ""
                     }
                 },
                 "tech": {
                     "ignition": "0",
                     "movestate": "3",
                     "power": "12.866",
                     "powerok": "1",
                     "engineon": "0",
                     "odometer": {
                         "value": "67508.8",
                         "valuetype": "H"
                     },
                     "worktime": "28.505555555556",
                     "fuel": {
                         "level": "16",
                         "leveltype": "P",
                         "range": "143"
                     },
                     "rpm": 1742,
                     "coolanttemp": 62,
                     "axleweight": 1500,
                     "tachodata": {
                         "driver1": "1132",
                         "driver2": "0000"
                     }
                     "indicators": {
                         "mask": "1111111111111111",
                         "active_mask": "0000000010001000"
                     },
                     "ignitioncrtl": {
                         "status": "0",
                         "phase": "0"
                     }
                 }
             }
         }
     },
     "result": "0",
     "resultdesc": "OK"
 }
Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
locator.key.request.statdescStringLocator object status description
locator.key.positionArray of ObjectArray of position objects
locator.key.position.maskHexHexadecimal mask of the information available for the position object. LSB order:

  • 0 – basic position information
  • 1 – ignition and movement state
  • 2 – temperature
  • 3 – power supply information
  • 4 – GPS fix information
  • 5 – speed information
  • 6 – odometer information
  • 7 – work time information
  • 8 – ignition control state
  • 9 – backup battery information
  • 10 – altitude information
  • 11 – identified driver information
locator.key.position.gpsObjectObject of the GPS related location information
locator.key.position.gps.timestampYYYYmmddHHiissLocation acquire date and time
locator.key.position.gps.expiredIntegerGPS location expired status:

  • 0 – not expired
  • 1 – expired
locator.key.position.gps.geopointObjectObject of geo point of the location
locator.key.position.gps.geopoint.latDoubleLatitude of the location
locator.key.position.gps.geopoint.lngDoubleLongitude of the location
locator.key.position.gps.geopoint.acquisitionStringType of the GPS acqisition:

  • GPS – from the GPS reading
  • GSM – based on the GSM triangulation
locator.key.position.gps.geopoint.accuracyIntegerAccuracy of the location, value roughly represents the location reading error in meters
locator.key.position.gps.headingObjectObject of heading values
locator.key.position.gps.geopoint.heading.valueIntegerHeading angle in degrees, 0 represents North
locator.key.position.gps.geopoint.heading.dirStringHeading direction:

  • N – North
  • NE – North-East
  • E – East
  • SE – South-East
  • S – South
  • SW – South-West
  • W – West
  • NW – North-West
locator.key.position.gps.geopoint.heading.gpsfixIntegerStatus of the GPS fix:

  • 0 – fix not acquired
  • 1 – fix OK
locator.key.position.gps.geopoint.heading.speedDoubleSpeed reading in kilometers per hour [km/h]
locator.key.position.gps.geopoint.heading.speedlimitIntegerStatus of the internal speed limit reach:

  • 0 – speed limit not reached
  • 1 – speed limit reached
locator.key.position.gps.geopoint.heading.altitudeDoubleAltitude above mean sea level reading in meters [m]
locator.key.position.techObjectObject of the device/vehicle related information
locator.key.position.tech.ignitionIntegerStatus of the ignition:

  • 0 – ignition off
  • 1 – ignition on
locator.key.position.tech.movestateIntegerMovement state:

  • 1 – ignition on and movement detected
  • 2 – ignition on movement not detected
  • 3 – ignition off
locator.key.position.tech.powerDoubleVoltage of the main power supply in Volts [V]
locator.key.position.tech.powerokIntegerMain power supply status:

  • 0 – power supply incorrect
  • 1 – power supply ok
locator.key.position.tech.engineonIntegerEngine status:

  • 0 – engine off
  • 1 – engine on
locator.key.position.tech.odometerObjectObject of the odometer information
locator.key.position.tech.odometer.valueDoubleOdometer value acquired from the internal GPS counter.
locator.key.position.tech.odometer.valuetypeStringType of odometer value:

  • H – kilometers [km]
  • I – impulses (not implemented yet)
locator.key.position.tech.fuelObjectObject of the fuel information
locator.key.position.tech.fuel.levelDoubleFuel level value
locator.key.position.tech.fuel.leveltypeStringType of fuel level value:

  • L – liters
  • P – percent
locator.key.position.tech.fuel.rangeDoublePossible range in [km] related to fuel level.
locator.key.position.tech.coolanttempDoubleCoolant temperature [Celcius degrees]
locator.key.position.tech.axleweightDoubleCurrent axle weight [kg]
locator.key.position.tech.rpmIntegerRevolutions per minute (RPM)
locator.key.position.tech.tachodataObjectObject of tachometer information
locator.key.position.tech.tachodata.driver1StringString mask informing about 1-st driver status

  1. Valid driver
  2. Card inserted
  3. Driver state
    0 – rest (sleeping)
    1 – driver available (short brake)
    2 – work (loading, unloading, working in an office)
    3 – drive (behind the wheel)
  4. Driver time limits
    0 – normal/no limits reached
    1 – 15min before 4.5 hours
    2 – 4.5 hours reached
    3 – 15min before 9 hours
    4 – 9 hours reached
    5 – 15min before 16 hours (not having 8 hours rest during last 24 hours)
    6 – 16 hours reached
    7 – other limits

Mask example: 1132 (card inserted, driver is valid, driving, 4.5 hours reached)

locator.key.position.tech.tachodata.driver2StringString mask informing about 2-nd driver status

  1. Valid driver
  2. Card inserted
  3. Driver state
    0 – rest (sleeping)
    1 – driver available (short brake)
    2 – work (loading, unloading, working in an office)
    3 – drive (behind the wheel)
  4. Driver time limits
    0 – normal/no limits reached
    1 – 15min before 4.5 hours
    2 – 4.5 hours reached
    3 – 15min before 9 hours
    4 – 9 hours reached
    5 – 15min before 16 hours (not having 8 hours rest during last 24 hours)
    6 – 16 hours reached
    7 – other limits

Mask example: 1132 (card inserted, driver is valid, driving, 4.5 hours reached)

locator.key.position.tech.indicatorsObjectObject of the indicators information
locator.key.position.tech.indicators.maskStringString mask informing which indicators are available. Each position is relaetd to specific indicator in following order:

  • 1. fuel level
  • 2. driver seat belt
  • 3. air condition
  • 4. cruise control
  • 5. brake pedal
  • 6. clutch pedal
  • 7. handbrake
  • 8. central lock
  • 9. reverse gear
  • 10. running lights
  • 11. low beams
  • 12. high beams
  • 13. rear foglights
  • 14. front foglights
  • 15. doors
  • 16. trunk

Mask example: 0001001001110000

locator.key.position.tech.indicators.active_maskStringString mask. Defining which of avaliable indicators are currently active.

  • 1 – active
  • 0 – inactive
locator.key.position.tech.worktimeDoubleLocator on time in hours [h]
locator.key.position.tech.ignitionctrlObjectObject of the ignition control information
locator.key.position.tech.ignitionctrl.statusIntegerStatus of the ignition controller:

  • 0 – ignition turned on
  • 1 – ignition turned off
locator.key.position.tech.ignitionctrl.phaseIntegerStatus of the shifting phase of the ignition controller:

  • 0 – status confirmed
  • 1 – status not confirmed
locator.key.position.tech.backupbatteryObjectObject of the backup battery information
locator.key.position.tech.backupbattery.levelIntegerStatus of the internal battery charge level in percentages of the full charge [%]
locator.key.position.tech.backupbattery.statusIntegerStatus of the internal battery:

  • 0 – battery OK
  • 2 – battery level low
  • 3 – battery almost dead
locator.key.position.extraObjectObject of the additional position information
locator.key.position.tech.extra.iconStringURL of the image representing current state of the locator
locator.key.position.extra.driverObjectObject of the detected driver
locator.key.position.tech.extra.driver.nameStringName of the detected driver
locator.key.position.tech.extra.driver.ibuttonHexIdentifier of the iButton card detected if the name of the driver cannot be determined

iaGetLocatorPosition

Function returns locator position of the locator reading closest to the specified date and time together with additional information regarding this reading

Query example:

 https://api.ikol.pl/iaGetLocatorPosition?login=user&password=pass&key=vehicle12345,locator67890×tamp=20150831130100&timezone=utc&output=json
 https://api.ikol.pl/iaGetLocatorPosition?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890×tamp=20150831130100&timezone=utc&output=json

Default limitations:
1 request per locator per 60 seconds

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
timestampYYYYmmddHHiissString representing timestamp of the requested locator position
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time both as an input and a result
Output example (JSON):

 {
	"locator": {
		"apikey1": {
			"request": {
				"stat": "0",
				"statdesc": "OK"
			},
			"position": {
				"mask": "231",
				"gps": {
					"timestamp": "20150531140352",
					"expired": "0",
					"geopoint": {
						"lat": "51.025617",
						"lng": "16.886183"
					},
					"acquisition": "GPS",
					"accuracy": "0",
					"heading": {
						"value": "128",
						"dir": "SE"
					},
					"gpsfix": "0",
					"speed": "0",
					"speedlimit": "0"
				},
				"extra": {
					"icon": "http://img.ikol.pl/graphics/icons/maps/v/carlugn_0_0_0_0_1_3_1_0.png"
				},
				"tech": {
					"backupbattery": {
						"level": "91",
						"status": "0"
					}
				}
			}
		},
		"apikey2": {
			"request": {
				"stat": "0",
				"statdesc": "OK"
			},
			"position": {
				"mask": "dfb",
				"gps": {
					"timestamp": "20150531142322",
					"expired": "0",
					"geopoint": {
						"lat": "52.169508",
						"lng": "20.938908"
					},
					"acquisition": "GPS",
					"accuracy": "1",
					"heading": {
						"value": "27",
						"dir": "NE"
					},
					"gpsfix": "1",
					"speed": "0",
					"speedlimit": "0",
					"altitude": "107.6"
				},
				"extra": {
					"icon": "http://img.ikol.pl/graphics/icons/maps/v/cartrkr_0_0_0_0_1_3_0_0.png",
					"driver": {
						"name": "Michau0142 Kowalski",
						"ibutton": ""
					}
				},
				"tech": {
					"ignition": "0",
					"movestate": "3",
					"power": "12.866",
					"powerok": "1",
					"engineon": "0",
					"odometer": {
						"value": "67508.8"
					},
					"worktime": "28.505555555556",
					"ignitioncrtl": {
						"status": "0",
						"phase": "0"
					}
				}
			}
		}
	},
	"result": "0",
	"resultdesc": "OK"
}
Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
locator.key.request.statdescStringLocator object status description
locator.key.positionArray of ObjectArray of position objects
locator.key.position.maskHexHexadecimal mask of the information available for the position object. LSB order:

  • 0 – basic position information
  • 1 – ignition and movement state
  • 2 – temperature
  • 3 – power supply information
  • 4 – GPS fix information
  • 5 – speed information
  • 6 – odometer information
  • 7 – work time information
  • 8 – ignition control state
  • 9 – backup battery information
  • 10 – altitude information
  • 11 – identified driver information
locator.key.position.gpsObjectObject of the GPS related location information
locator.key.position.gps.timestampYYYYmmddHHiissLocation acquire date and time
locator.key.position.gps.expiredIntegerGPS location expired status:

  • 0 – not expired
  • 1 – expired
locator.key.position.gps.geopointObjectObject of geo point of the location
locator.key.position.gps.geopoint.latDoubleLatitude of the location
locator.key.position.gps.geopoint.lngDoubleLongitude of the location
locator.key.position.gps.geopoint.acquisitionStringType of the GPS acqisition:

  • GPS – from the GPS reading
  • GSM – based on the GSM triangulation
locator.key.position.gps.geopoint.accuracyIntegerAccuracy of the location, value roughly represents the location reading error in meters
locator.key.position.gps.headingObjectObject of heading values
locator.key.position.gps.geopoint.heading.valueIntegerHeading angle in degrees, 0 represents North
locator.key.position.gps.geopoint.heading.dirStringHeading direction:

  • N – North
  • NE – North-East
  • E – East
  • SE – South-East
  • S – South
  • SW – South-West
  • W – West
  • NW – North-West
locator.key.position.gps.geopoint.heading.gpsfixIntegerStatus of the GPS fix:

  • 0 – fix not acquired
  • 1 – fix OK
locator.key.position.gps.geopoint.heading.speedDoubleSpeed reading in kilometers per hour [km/h]
locator.key.position.gps.geopoint.heading.speedlimitIntegerStatus of the internal speed limit reach:

  • 0 – speed limit not reached
  • 1 – speed limit reached
locator.key.position.gps.geopoint.heading.altitudeDoubleAltitude above mean sea level reading in meters [m]
locator.key.position.techObjectObject of the device/vehicle related information
locator.key.position.tech.ignitionIntegerStatus of the ignition:

  • 0 – ignition off
  • 1 – ignition on
locator.key.position.tech.movestateIntegerMovement state:

  • 1 – ignition on and movement detected
  • 2 – ignition on movement not detected
  • 3 – ignition off
locator.key.position.tech.powerDoubleVoltage of the main power supply in Volts [V]
locator.key.position.tech.powerokIntegerMain power supply status:

  • 0 – power supply incorrect
  • 1 – power supply ok
locator.key.position.tech.engineonIntegerEngine status:

  • 0 – engine off
  • 1 – engine on
locator.key.position.tech.odometerObjectObject of the odometer information
locator.key.position.tech.odometer.valueDoubleOdometer value acquired from the internal GPS counter in kilometers [km]
locator.key.position.tech.worktimeDoubleLocator on time in hours [h]
locator.key.position.tech.ignitionctrlObjectObject of the ignition control information
locator.key.position.tech.ignitionctrl.statusIntegerStatus of the ignition controller:

  • 0 – ignition turned on
  • 1 – ignition turned off
locator.key.position.tech.ignitionctrl.phaseIntegerStatus of the shifting phase of the ignition controller:

  • 0 – status confirmed
  • 1 – status not confirmed
locator.key.position.tech.backupbatteryObjectObject of the backup battery information
locator.key.position.tech.backupbattery.levelIntegerStatus of the internal battery charge level in percentages of the full charge [%]
locator.key.position.tech.backupbattery.statusIntegerStatus of the internal battery:

  • 0 – battery OK
  • 2 – battery level low level
  • 3 – battery almost dead
locator.key.position.extraObjectObject of the additional position information
locator.key.position.tech.extra.iconStringURL of the image representing current state of the locator
locator.key.position.extra.driverObjectObject of the detected driver
locator.key.position.tech.extra.driver.nameStringName of the detected driver
locator.key.position.tech.extra.driver.ibuttonHexIdentifier of the iButton card detected if the name of the driver cannot be determined

iaGetLocatorLastNotifications

Function returns locator’s last available notification events since the specified date and time or time offset

Query example:

 https://api.ikol.pl/iaGetLocatorLastNotifications?login=user&password=pass&mask=80&timezone=utc&output=json
 https://api.ikol.pl/iaGetLocatorLastNotifications?sid=rokm0290p8qvgke2d5114df85&mask=80&timezone=utc&output=json

Default limitations:
1 request per locator per 5 minutes

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys. If no key is provided function will produce report for all available locators.
starttimeYYYYmmddHHiissString representing start of the requested notification report, default value is the time of one hour before current time
offset_timeIntegerNumber of minutes before the current time when the requested notification report should start (this serves as an alternative to providing starttime paramter)
timestamp_type[create|event]If the timestamp type is set to „event” function will return all the notifications that happened within the requested time span, if timestamp type is set to „create” function will return all the notifications that were delivered to the system within the requested time span (the latter may be used for getting uniquely stored notification events).
maskHexHexadecimal mask of requested notification types (default value is 3fff).
LSB order:

  • 0 – harsh braking
  • 1 – harsh acceleration
  • 2 – reserved
  • 3 – harsh turning
  • 4 – geo fence border
  • 5 – SOS button
  • 6 – speed limit threshold
  • 7 – iginition/movement change
  • 8 – GSM jamming
  • 9 – long stop
  • 10 – long movement
  • 11 – digital input alert
  • 12 – ikol X power
  • 13 – ikol X wifi connection
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time both as an input and a result
Output example (JSON):

{
	"locator": {
		"vehicle12345": {
			"notifications": [{
				"id": "I3:5593cd",
				"event": "80",
				"timestamp": "20161025172141",
				"params": {
					"action": "0"
				},
				"geopoint": {
					"lat": "52.379023",
					"lng": "20.917542"
				}
			},
			{
				"id": "I3:5591ad",
				"event": "10",
				"timestamp": "20161025171526",
				"params": {
					"action": "0",
					"name": "workplace",
					"key": "vehicle12345:workplace",
					"stat": "1"
				},
				"geopoint": {
					"lat": "52.134878",
					"lng": "20.976235"
				}
			},
			{
				"id": "I3:558fae",
				"event": "80",
				"timestamp": "20161025170320",
				"params": {
					"action": "1"
				},
				"geopoint": {
					"lat": "52.404122",
					"lng": "20.877599"
				}
			},
			{
				"id": "I3:5580e7",
				"event": "1",
				"timestamp": "20161025155802",
				"geopoint": {
					"lat": "52.379614",
					"lng": "20.912762"
				}
			},
			{
				"id": "I3:5578db",
				"event": "10",
				"timestamp": "20161025152324",
				"params": {
					"action": "1",
					"name": "school",
					"key": "vehicle12345:school",
					"stat": "1"
				},
				"geopoint": {
					"lat": "52.138478",
					"lng": "20.97694"
				}
			},
			{
				"id": "I3:54feaa",
				"event": "10",
				"timestamp": "20161025054303",
				"params": {
					"action": "0",
					"name": "Garden State",
					"key": "vehicle12345:gardenstate",
					"stat": "1"
				},
				"geopoint": {
					"lat": "52.1151",
					"lng": "20.973816"
				}
			}],
			"request": {
				"stat": "0",
				"statdesc": "OK"
			}
		},
		"locator67890": {
			"notifications": [{
				"id": "I1:411af2d",
				"event": "80",
				"timestamp": "20161025180248",
				"params": {
					"action": "0"
				},
				"geopoint": {
					"lat": "52.140189",
					"lng": "21.041366"
				}
			},
			{
				"id": "I1:411a602",
				"event": "80",
				"timestamp": "20161025172707",
				"params": {
					"action": "1"
				},
				"geopoint": {
					"lat": "52.140189",
					"lng": "21.041366"
				}
			}],
			"request": {
				"stat": "0",
				"statdesc": "OK"
			}
		}
	},
	"result": "0",
	"resultdesc": "OK"
}
Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
  • 7 – Time span of the requested report exceeds its limits
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
  • 4 – Contract does not have track service enabled
  • 5 – Request exceeds available position history depth for this contract
locator.key.request.statdescStringLocator object status description
locator.key.notificationsArray of ObjectsArray of notification objects
locator.key.notifications[n].idStringNotification event unique identifier
locator.key.notifications[n].eventHexHexadecimal representation of the notification event

  • 1 – Harsh braking
  • 2 – Harsh acceleration
  • 8 – Harsh turning
  • 10 – Geo fence border
  • 20 – SOS button
  • 40 – Speed limit threshold
  • 80 – Iginition/movement change
  • 100 – GSM jamming
  • 200 – Long stop
  • 400 – Long movement
  • 800 – Digital input alert
  • 1000 – Power button (ikol x)
  • 2000 – WiFi connection (ikol x)
locator.key.notifications[n].timestampYYYYmmddHHiissNotification event date and time
locator.key.notifications[n].paramsObjectsObject of notification event parameters
locator.key.notifications[n].params.actionIntegerFor event 10:

  • 0 – Exits geo zone
  • 1 – Enters geo zone

For event 40:

  • 0 – Speed drops below limit threshold
  • 1 – Speed exceeds limit threshold

For event 80:

  • 0 – Ignition off/Movement stops
  • 1 – Ignition on/Movement starts

For event 800:

  • 0 – Digital input disactivated
  • 1 – Digital input activated

For event 1000:

  • 0 – Power off
  • 1 – Power on

For event 2000:

  • 0 – WiFi network disconnected
  • 1 – WiFi network connected
locator.key.notifications[n].params.nameStringFor event 10: Name of the geo zone
For event 200: Long stop period
For event 400: Long movement period
For event 800: Digital input name
locator.key.notifications[n].params.keyStringAPI key of the alert that triggered notification
locator.key.notifications[n].params.statIntegerStatus of the alert that triggered notification
locator.key.notifications[n].geopointObjectsObject of geo point of the notification event
locator.key.notifications[n].geopoint.latDoubleLatitude of the notification event
locator.key.notifications[n].geopoint.lngDoubleLongitude of the notification event

iaGetLocatorNotifications

Function returns locator’s notification events within the specified date and time span

Query example:

 https://api.ikol.pl/iaGetLocatorNotifications?login=user&password=pass&key=vehicle12345,locator67890&starttime=20150831130100&stoptime=20150831235959&timezone=utc&output=json
 https://api.ikol.pl/iaGetLocatorNotifications?sid=rokm0290p8qvgke2d5114df85&key=vehicle12345,locator67890&starttime=20150831130100&stoptime=20150831235959&timezone=utc&output=json

Default limitations:
1 request per locator per 5 minutes
Time span of the requested report may not exceed 24 hours

Query parameterFormatDescription
loginStringIdentifier of a user who is granted API access to at least one of the customer’s locators
passwordStringUser password
sidStringSession identifier (this parameter is provided when session authentication method is used)
keyString[,String]Comma separated locator API keys
starttimeYYYYmmddHHiissString representing start of the requested notification report, default value is the time of one before current time
stoptimeYYYYmmddHHiissString representing stop of the requested trip report, default value is the current time
maskHexHexadecimal mask of requested notification types (default value is 3fff).
LSB order:

  • 0 – harsh braking
  • 1 – harsh acceleration
  • 2 – reserved
  • 3 – harsh turning
  • 4 – geo fence border
  • 5 – SOS button
  • 6 – speed limit threshold
  • 7 – iginition/movement change
  • 8 – GSM jamming
  • 9 – long stop
  • 10 – long movement
  • 11 – digital input alert
  • 12 – ikol X power
  • 13 – ikol X wifi connection
output[xml|json]Output format
timezone[local|utc]Defines what time zone should be used to represent date and time both as an input and a result
Output example (JSON):

{
	"locator": {
		"vehicle12345": {
			"notifications": [{
				"id": "I3:5593cd",
				"event": "80",
				"timestamp": "20161025172141",
				"params": {
					"action": "0"
				},
				"geopoint": {
					"lat": "52.379023",
					"lng": "20.917542"
				}
			},
			{
				"id": "I3:5591ad",
				"event": "10",
				"timestamp": "20161025171526",
				"params": {
					"action": "0",
					"name": "workplace",
					"key": "vehicle12345:workplace",
					"stat": "1"
				},
				"geopoint": {
					"lat": "52.134878",
					"lng": "20.976235"
				}
			},
			{
				"id": "I3:558fae",
				"event": "80",
				"timestamp": "20161025170320",
				"params": {
					"action": "1"
				},
				"geopoint": {
					"lat": "52.404122",
					"lng": "20.877599"
				}
			},
			{
				"id": "I3:5580e7",
				"event": "1",
				"timestamp": "20161025155802",
				"geopoint": {
					"lat": "52.379614",
					"lng": "20.912762"
				}
			},
			{
				"id": "I3:5578db",
				"event": "10",
				"timestamp": "20161025152324",
				"params": {
					"action": "1",
					"name": "school",
					"key": "vehicle12345:school",
					"stat": "1"
				},
				"geopoint": {
					"lat": "52.138478",
					"lng": "20.97694"
				}
			},
			{
				"id": "I3:54feaa",
				"event": "10",
				"timestamp": "20161025054303",
				"params": {
					"action": "0",
					"name": "Garden State",
					"key": "vehicle12345:gardenstate",
					"stat": "1"
				},
				"geopoint": {
					"lat": "52.1151",
					"lng": "20.973816"
				}
			}],
			"request": {
				"stat": "0",
				"statdesc": "OK"
			}
		},
		"locator67890": {
			"notifications": [{
				"id": "I1:411af2d",
				"event": "80",
				"timestamp": "20161025180248",
				"params": {
					"action": "0"
				},
				"geopoint": {
					"lat": "52.140189",
					"lng": "21.041366"
				}
			},
			{
				"id": "I1:411a602",
				"event": "80",
				"timestamp": "20161025172707",
				"params": {
					"action": "1"
				},
				"geopoint": {
					"lat": "52.140189",
					"lng": "21.041366"
				}
			}],
			"request": {
				"stat": "0",
				"statdesc": "OK"
			}
		}
	},
	"result": "0",
	"resultdesc": "OK"
}
Reply fieldFormatDescription
resultIntegerNumerical code of the result:

  • 0 – OK
  • 1 – Request not recognized
  • 2 – SSL is required and not detected
  • 3 – Authorization failure
  • 4 – Customer does not have API service enabled
  • 5 – API request limit has been reached
  • 6 – No API key is provided
  • 7 – Time span of the requested report exceeds its limits
resultdescStringResult description
locatorArray of ObjectsArray of locator objects identified by locator API key
locator.key.requestObjectObject of locator request status
locator.key.request.statIntegerNumerical code of the locator object status:

  • 0 – OK
  • 1 – Locator or contract is not active or does not exist
  • 2 – Contract does not have API service enabled
  • 3 – User does not have sufficient rights
  • 4 – Contract does not have track service enabled
  • 5 – Request exceeds available position history depth for this contract
locator.key.request.statdescStringLocator object status description
locator.key.notificationsArray of ObjectsArray of notification objects
locator.key.notifications[n].idStringNotification event unique identifier
locator.key.notifications[n].eventHexHexadecimal representation of the notification event

  • 1 – Harsh braking
  • 2 – Harsh acceleration
  • 8 – Harsh turning
  • 10 – Geo fence border
  • 20 – SOS button
  • 40 – Speed limit threshold
  • 80 – Iginition/movement change
  • 100 – GSM jamming
  • 200 – Long stop
  • 400 – Long movement
  • 800 – Digital input alert
  • 1000 – Power button (ikol x)
  • 2000 – WiFi connection (ikol x)
locator.key.notifications[n].timestampYYYYmmddHHiissNotification event date and time
locator.key.notifications[n].paramsObjectsObject of notification event parameters
locator.key.notifications[n].params.actionIntegerFor event 10:

  • 0 – Exits geo zone
  • 1 – Enters geo zone

For event 40:

  • 0 – Speed drops below limit threshold
  • 1 – Speed exceeds limit threshold

For event 80:

  • 0 – Ignition off/Movement stops
  • 1 – Ignition on/Movement starts

For event 800:

  • 0 – Digital input disactivated
  • 1 – Digital input activated

For event 1000:

  • 0 – Power off
  • 1 – Power on

For event 2000:

  • 0 – WiFi network disconnected
  • 1 – WiFi network connected
locator.key.notifications[n].params.nameStringFor event 10: Name of the geo zone
For event 200: Long stop period
For event 400: Long movement period
For event 800: Digital input name
locator.key.notifications[n].params.keyStringAPI key of the alert that triggered notification
locator.key.notifications[n].params.statIntegerStatus of the alert that triggered notification
locator.key.notifications[n].geopointObjectsObject of geo point of the notification event
locator.key.notifications[n].geopoint.latDoubleLatitude of the notification event
locator.key.notifications[n].geopoint.lngDoubleLongitude of the notification event

Examples of implementation

Getting locator information in PHP

<?php 
 /* 
 * Example of getting locator information via ikol API (HTTPS) in json format
 */ 
 //API user login 
 $login = "demo@ikol.com"; 
 //API user password 
 $password = "demo"; 
 //API script URL
 $url = "https://api.ikol.pl/"; 
 //Name of the API function
 $function = "iaGetLocatorTrips";
 //API keys of the locators
 $keys = array('apikey1', 'apikey2');
 // output format
 $output = 'json';
 
 // compse URI
 $uri = $url . $function . '?login=' . $login . '&password=' . $password .'&key='. implode(',', $keys) .'&output=' . $output; 
 
 // create curl resource
 $ch = curl_init();
 
 // set url
 curl_setopt($ch, CURLOPT_URL, $uri);
 
 //return the transfer as a string
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
 
 // $output contains the output string
 $output = curl_exec($ch);
 
 // close curl resource to free up system resources
 curl_close($ch); 
 
 $output_object = json_decode($output);
 
 print_r($output_object);
 //.....
?> 

Getting locator trips in Android Java

public class ApiConnection {
    /* 
    * Example of getting locator trips via ikol API (HTTPS) in json format
    */     
    // API script URL
    private String url_host = "https://api.ikol.pl/";
    // Name of the API function
    private String url_function_iaGetLocatorTrips = "iaGetLocatorTrips?";
    // Set timeout
    private final int TIMEOUT = 10000;
    
    private String url_sid = "sid=";
    private String url_key = "&key=";
    private String url_starttime = "&starttime=";
    private String url_stoptime = "&stoptime=";
    private String url_timezone = "&timezone=utc";
    private String url_output_json = "&output=json";
    private String url_route_true = "&route=true";
    private String url_appkey = "&appkey=YOURAPPKEY";
    
    public void iaGetLocatorTrips(String sid, String key, String starttime, String stoptime) {
        // compse URI
        String urlString = url_host   url_function_iaGetLocatorTrips   url_sid   sid   url_key   key
                 url_starttime   starttime   url_stoptime   stoptime   url_timezone   url_output_json 
                 url_route_true   url_appkey;
        URL url = new URL(new String(urlString.getBytes(), "UTF-8"));
        
        HttpURLConnection con = (HttpURLConnection) url.openConnection();
        con.setRequestMethod("GET");
        con.setConnectTimeout(TIMEOUT);
        con.setReadTimeout(TIMEOUT);
        BufferedReader in = new BufferedReader(
                new InputStreamReader(con.getInputStream())
        );
        String inputLine;
        response = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close(); 
        
        // result contains the output string
        String result = response.toString();
        // jsonObject to parse
        JSONObject jsonObject = new JSONObject(result);    
        //..........
    }
}