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:

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.
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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session 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 parameter	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
version	Object	Version object
version.author	String	API author
version.version	String	API version and subversion
version.development	String	Development 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 parameter	Format	Description
login	String	Identifier of a user who is granted API acces to at least one of the customer’s locators
password	String	User password
appkey	String	Application API key (parameter used only for ikol certified applications that require application level API key)
gcm_id	String	Optional parameter that represents GCM id
gcm_stat	Integer	When 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
version	String	Application 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 parameter	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
user	Object	User object
user.name	String	Name of the logged user
user.last_name	String	Last name of the logged user
sid	String	Session identifier

iaLogoutSession

Function terminates existing user session

Query example:

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

Default limitations:
No limitations

Query parameter	Format	Description
sid	String	Session identifier
output	[xml\|json]	Output format

Output example (JSON):

 {
	"result": "0",
	"resultdesc": "OK"
 }

Query parameter

Format

Description

result

Integer

Numerical 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

resultdesc

String

Result 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
access_rights	String	Name 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 parameter	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locators	Array of Objects	Array of user locators
locators[n].group	Object	Object of locator’s group
locators[n].group.name	String	Group name
locators[n].group.order	Integer	Group 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].generalinfo	Object	Object of locator general information
locators[n].generalinfo.key	String	Locator API key
locators[n].generalinfo.id	String	Locator unique identifier
locators[n].generalinfo.platform	Char[1]	Locator mobility platform: V – vehicle powered locator P – portable locator M – mobile locator (ikol x platform)
locators[n].display	Object	Object of locator display information
locators[n].display.label	String	Locator display label
locators[n].display.icon	String	URL of the icon assigned to the locator
locators[n].users	Object	Object of locator user assignments
locators[n].users.mainuser	String	Locator main user name
locators[n].vehicle	Object	If locator’s platform is Vehicle this object contains vehicle information
locators[n].vehicle.make	String	Vehicle make
locators[n].vehicle.model	String	Vehicle model
locators[n].vehicle.plateid	String	Vehicle plate number (registration number)
locators[n].vehicle.vin	String	Vehicle identification number (VIN)
locators[n].device	Object	If locator’s platform is Mobile this object contains mobile device information
locators[n].device.name	String	Name of the type of the device
locators[n].device.make	String	Device 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,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 parameter	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
users	Array of Objects	Array 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.login	String	User login
users.key.name	String	User name
users.key.surname	String	User surname
users.key.email	String	User email
users.key.phone	String	User phone
users.key.activitydate	YYYYmmddHHiiss	Last user activity (last login)
users.key.picture	String	User picture
users.key.stat	Integer	Status
users.key.statdesc	String	User 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,String]	Comma separated locator API keys
date	String	Year 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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
stat	Integer	Numerical 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
statdesc	String	Query status description for given locators.
days	Array Of String	Array 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,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 parameter	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.odometer	Object	Object of locator odometer readouts
locator.key.odometer.value	Double	Locator internal odometer value in km
locator.key.odometer.timestamp	YYYYmmddHHiiss	Date and time of the odometer readout
locator.key.odometer.valuecan	Double	Odometer value in km retrieved from the CAN bus of the vehicle
locator.key.odometer.timestampcan	YYYYmmddHHiiss	Date 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,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 parameter	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.generalinfo	Object	Object of locator general information
locator.key.generalinfo.id	String	Locator unique identifier
locator.key.generalinfo.hardware	String	Version of locator hardware
locator.key.generalinfo.platform	Char[1]	Locator mobility platform: V – vehicle powered locator P – portable locator M – mobile locator (ikol x platform)
locator.key.display	Object	Object of locator display information
locator.key.display.label	String	Locator display label
locator.key.display.icon	String	URL of the icon assigned to the locator
locator.key.users	Object	Object of locator user assignments
locator.key.users.mainuser	String	Locator main user name
locator.key.vehicle	Object	If locator’s platform is Vehicle this object contains vehicle information
locator.key.vehicle.make	String	Vehicle make
locator.key.vehicle.model	String	Vehicle model
locator.key.vehicle.plateid	String	Vehicle plate number (registration number)
locator.key.vehicle.vin	String	Vehicle identification number (VIN)
locator.key.device	Object	If locator’s platform is Mobile this object contains mobile device information
locator.key.device.name	String	Name of the type of the device
locator.key.device.make	String	Device 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,String]	Comma separated locator API keys
starttime	YYYYmmddHHiiss	String representing start of the requested trip report, default value is the beginning of the current day
stoptime	YYYYmmddHHiiss	String 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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.trips	Array of Object	Array of trip objects
locator.key.trips[n].journey	Object	Object of trip movement information
locator.key.trips[n].journey.timestamp	YYYYmmddHHiiss	Journey start date and time
locator.key.trips[n].journey.distance	Integer	Journey distance in meters
locator.key.trips[n].journey.duration	Integer	Journey duration in seconds. -1 is returned if the duration may not be provided
locator.key.trips[n].journey.geopoint	Object	Object of geo point of the trip start location
locator.key.trips[n].journey.geopoint.lat	Double	Latitude of the trip start location
locator.key.trips[n].journey.geopoint.lng	Double	Longitude of the trip start location
locator.key.trips[n].journey.usetype	Integer	Trip 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.route	String	Encoded trip route (consult Encoded Polyline Algorithm Format)
locator.key.trips[n].journey.fuelused	Double	Fuel used during the trip in liters, information is available if „CAN support” service is enabled for this locator
locator.key.trips[n].journey.fuelconsumption	Double	Fuel consumption during the trip in liters per 100km, information is available if „CAN support” service is enabled for this locator
locator.key.trips[n].attitude	Object	Object of user driving attitudes
locator.key.trips[n].attitude.accel	Integer	Harsh accelerations count
locator.key.trips[n].attitude.brake	Integer	Harsh brakes count
locator.key.trips[n].attitude.overrpm	Integer	High engine RPM’s count
locator.key.trips[n].attitude.overspeed	Integer	Overspeeds count
locator.key.trips[n].attitude.turn	Integer	Harsh turns count
locator.key.trips[n].stop	Object	Object of trip stop information
locator.key.trips[n].stop.timestamp	YYYYmmddHHiiss	Journey stop date and time
locator.key.trips[n].stop.duration	Integer	Stop duration in seconds. -1 is returned of the duration may not be provided.
locator.key.trips[n].stop.geopoint	Object	Object of geo point of the trip stop location
locator.key.trips[n].stop.geopoint.lat	Double	Latitude of the trip stop location
locator.key.trips[n].stop.geopoint.lng	Double	Longitude of the trip stop location
locator.key.trips[n].stop.address	Object	Object 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.country	String	Country of the stop location address
locator.key.trips[n].stop.address.region	String	Region/District/State of the stop location address
locator.key.trips[n].stop.address.city	String	City of the stop location address
locator.key.trips[n].stop.address.street	String	Street of the stop location address
locator.key.trips[n].stop.point	Object	Object 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.name	String	Name of the point/customer
locator.key.trips[n].stop.point.type	String	Point type name
locator.key.trips[n].stop.point.global	String	Point global status: 0 – account specific point/customer 1 – global point/customer
locator.key.tripinfo	Object	Object of all requested trips summary
locator.key.tripinfo.count	Integer	Count of all trips of the locator
locator.key.tripinfo.summary	Object	Object of summary data of the trips if at least one trip is returned
locator.key.tripinfo.summary.journeydistance	Integer	Total trips distance in meters
locator.key.tripinfo.summary.journeyduration	Integer	Total trips duration in seconds
locator.key.tripinfo.summary.stopduration	Integer	Total stops duration in seconds
locator.key.tripinfo.summary.totalfuelused	Double	Total fuel used in liters
locator.key.tripinfo.summary.totalfuelconsumption	Double	Total average fuel consumption in liters per 100km
locator.key.tripinfo.summary.attitude	Object	Object of summary data of the trip attitude exceptions
locator.key.tripinfo.summary.attitude.mask	Hex	Hexadecimal 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.accel	Integer	Harsh accelerations count
locator.key.tripinfo.summary.attitude.brake	Integer	Harsh braking count
locator.key.tripinfo.summary.attitude.turn	Integer	Harsh turns count
locator.key.tripinfo.summary.attitude.overspeed	Integer	Overspeeds count
locator.key.tripinfo.summary.attitude.overrpm	Integer	High 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,String]	Comma separated locator API keys
threshold_time	YYYYmmddHHiiss	String representing threshold day in or before which trip day is looked for (dafault value is current day)
only_real	1\|0	Whether 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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.day	YYYYmmdd	Date 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.position	Array of Object	Array of position objects
locator.key.position.mask	Hex	Hexadecimal 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.gps	Object	Object of the GPS related location information
locator.key.position.gps.timestamp	YYYYmmddHHiiss	Location acquire date and time
locator.key.position.gps.expired	Integer	GPS location expired status: 0 – not expired 1 – expired
locator.key.position.gps.geopoint	Object	Object of geo point of the location
locator.key.position.gps.geopoint.lat	Double	Latitude of the location
locator.key.position.gps.geopoint.lng	Double	Longitude of the location
locator.key.position.gps.geopoint.acquisition	String	Type of the GPS acqisition: GPS – from the GPS reading GSM – based on the GSM triangulation
locator.key.position.gps.geopoint.accuracy	Integer	Accuracy of the location, value roughly represents the location reading error in meters
locator.key.position.gps.heading	Object	Object of heading values
locator.key.position.gps.geopoint.heading.value	Integer	Heading angle in degrees, 0 represents North
locator.key.position.gps.geopoint.heading.dir	String	Heading 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.gpsfix	Integer	Status of the GPS fix: 0 – fix not acquired 1 – fix OK
locator.key.position.gps.geopoint.heading.speed	Double	Speed reading in kilometers per hour [km/h]
locator.key.position.gps.geopoint.heading.speedlimit	Integer	Status of the internal speed limit reach: 0 – speed limit not reached 1 – speed limit reached
locator.key.position.gps.geopoint.heading.altitude	Double	Altitude above mean sea level reading in meters [m]
locator.key.position.tech	Object	Object of the device/vehicle related information
locator.key.position.tech.ignition	Integer	Status of the ignition: 0 – ignition off 1 – ignition on
locator.key.position.tech.movestate	Integer	Movement state: 1 – ignition on and movement detected 2 – ignition on movement not detected 3 – ignition off
locator.key.position.tech.power	Double	Voltage of the main power supply in Volts [V]
locator.key.position.tech.powerok	Integer	Main power supply status: 0 – power supply incorrect 1 – power supply ok
locator.key.position.tech.engineon	Integer	Engine status: 0 – engine off 1 – engine on
locator.key.position.tech.odometer	Object	Object of the odometer information
locator.key.position.tech.odometer.value	Double	Odometer value acquired from the internal GPS counter.
locator.key.position.tech.odometer.valuetype	String	Type of odometer value: H – kilometers [km] I – impulses (not implemented yet)
locator.key.position.tech.fuel	Object	Object of the fuel information
locator.key.position.tech.fuel.level	Double	Fuel level value
locator.key.position.tech.fuel.leveltype	String	Type of fuel level value: L – liters P – percent
locator.key.position.tech.fuel.range	Double	Possible range in [km] related to fuel level.
locator.key.position.tech.coolanttemp	Double	Coolant temperature [Celcius degrees]
locator.key.position.tech.axleweight	Double	Current axle weight [kg]
locator.key.position.tech.rpm	Integer	Revolutions per minute (RPM)
locator.key.position.tech.tachodata	Object	Object of tachometer information
locator.key.position.tech.tachodata.driver1	String	String mask informing about 1-st driver status Valid driver Card inserted Driver state 0 – rest (sleeping) 1 – driver available (short brake) 2 – work (loading, unloading, working in an office) 3 – drive (behind the wheel) 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.driver2	String	String mask informing about 2-nd driver status Valid driver Card inserted Driver state 0 – rest (sleeping) 1 – driver available (short brake) 2 – work (loading, unloading, working in an office) 3 – drive (behind the wheel) 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.indicators	Object	Object of the indicators information
locator.key.position.tech.indicators.mask	String	String 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_mask	String	String mask. Defining which of avaliable indicators are currently active. 1 – active 0 – inactive
locator.key.position.tech.worktime	Double	Locator on time in hours [h]
locator.key.position.tech.ignitionctrl	Object	Object of the ignition control information
locator.key.position.tech.ignitionctrl.status	Integer	Status of the ignition controller: 0 – ignition turned on 1 – ignition turned off
locator.key.position.tech.ignitionctrl.phase	Integer	Status of the shifting phase of the ignition controller: 0 – status confirmed 1 – status not confirmed
locator.key.position.tech.backupbattery	Object	Object of the backup battery information
locator.key.position.tech.backupbattery.level	Integer	Status of the internal battery charge level in percentages of the full charge [%]
locator.key.position.tech.backupbattery.status	Integer	Status of the internal battery: 0 – battery OK 2 – battery level low 3 – battery almost dead
locator.key.position.extra	Object	Object of the additional position information
locator.key.position.tech.extra.icon	String	URL of the image representing current state of the locator
locator.key.position.extra.driver	Object	Object of the detected driver
locator.key.position.tech.extra.driver.name	String	Name of the detected driver
locator.key.position.tech.extra.driver.ibutton	Hex	Identifier 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,String]	Comma separated locator API keys
timestamp	YYYYmmddHHiiss	String 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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.position	Array of Object	Array of position objects
locator.key.position.mask	Hex	Hexadecimal 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.gps	Object	Object of the GPS related location information
locator.key.position.gps.timestamp	YYYYmmddHHiiss	Location acquire date and time
locator.key.position.gps.expired	Integer	GPS location expired status: 0 – not expired 1 – expired
locator.key.position.gps.geopoint	Object	Object of geo point of the location
locator.key.position.gps.geopoint.lat	Double	Latitude of the location
locator.key.position.gps.geopoint.lng	Double	Longitude of the location
locator.key.position.gps.geopoint.acquisition	String	Type of the GPS acqisition: GPS – from the GPS reading GSM – based on the GSM triangulation
locator.key.position.gps.geopoint.accuracy	Integer	Accuracy of the location, value roughly represents the location reading error in meters
locator.key.position.gps.heading	Object	Object of heading values
locator.key.position.gps.geopoint.heading.value	Integer	Heading angle in degrees, 0 represents North
locator.key.position.gps.geopoint.heading.dir	String	Heading 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.gpsfix	Integer	Status of the GPS fix: 0 – fix not acquired 1 – fix OK
locator.key.position.gps.geopoint.heading.speed	Double	Speed reading in kilometers per hour [km/h]
locator.key.position.gps.geopoint.heading.speedlimit	Integer	Status of the internal speed limit reach: 0 – speed limit not reached 1 – speed limit reached
locator.key.position.gps.geopoint.heading.altitude	Double	Altitude above mean sea level reading in meters [m]
locator.key.position.tech	Object	Object of the device/vehicle related information
locator.key.position.tech.ignition	Integer	Status of the ignition: 0 – ignition off 1 – ignition on
locator.key.position.tech.movestate	Integer	Movement state: 1 – ignition on and movement detected 2 – ignition on movement not detected 3 – ignition off
locator.key.position.tech.power	Double	Voltage of the main power supply in Volts [V]
locator.key.position.tech.powerok	Integer	Main power supply status: 0 – power supply incorrect 1 – power supply ok
locator.key.position.tech.engineon	Integer	Engine status: 0 – engine off 1 – engine on
locator.key.position.tech.odometer	Object	Object of the odometer information
locator.key.position.tech.odometer.value	Double	Odometer value acquired from the internal GPS counter in kilometers [km]
locator.key.position.tech.worktime	Double	Locator on time in hours [h]
locator.key.position.tech.ignitionctrl	Object	Object of the ignition control information
locator.key.position.tech.ignitionctrl.status	Integer	Status of the ignition controller: 0 – ignition turned on 1 – ignition turned off
locator.key.position.tech.ignitionctrl.phase	Integer	Status of the shifting phase of the ignition controller: 0 – status confirmed 1 – status not confirmed
locator.key.position.tech.backupbattery	Object	Object of the backup battery information
locator.key.position.tech.backupbattery.level	Integer	Status of the internal battery charge level in percentages of the full charge [%]
locator.key.position.tech.backupbattery.status	Integer	Status of the internal battery: 0 – battery OK 2 – battery level low level 3 – battery almost dead
locator.key.position.extra	Object	Object of the additional position information
locator.key.position.tech.extra.icon	String	URL of the image representing current state of the locator
locator.key.position.extra.driver	Object	Object of the detected driver
locator.key.position.tech.extra.driver.name	String	Name of the detected driver
locator.key.position.tech.extra.driver.ibutton	Hex	Identifier 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,String]	Comma separated locator API keys. If no key is provided function will produce report for all available locators.
starttime	YYYYmmddHHiiss	String representing start of the requested notification report, default value is the time of one hour before current time
offset_time	Integer	Number 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).
mask	Hex	Hexadecimal 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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.notifications	Array of Objects	Array of notification objects
locator.key.notifications[n].id	String	Notification event unique identifier
locator.key.notifications[n].event	Hex	Hexadecimal 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].timestamp	YYYYmmddHHiiss	Notification event date and time
locator.key.notifications[n].params	Objects	Object of notification event parameters
locator.key.notifications[n].params.action	Integer	For 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.name	String	For 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.key	String	API key of the alert that triggered notification
locator.key.notifications[n].params.stat	Integer	Status of the alert that triggered notification
locator.key.notifications[n].geopoint	Objects	Object of geo point of the notification event
locator.key.notifications[n].geopoint.lat	Double	Latitude of the notification event
locator.key.notifications[n].geopoint.lng	Double	Longitude 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 parameter	Format	Description
login	String	Identifier of a user who is granted API access to at least one of the customer’s locators
password	String	User password
sid	String	Session identifier (this parameter is provided when session authentication method is used)
key	String[,String]	Comma separated locator API keys
starttime	YYYYmmddHHiiss	String representing start of the requested notification report, default value is the time of one before current time
stoptime	YYYYmmddHHiiss	String representing stop of the requested trip report, default value is the current time
mask	Hex	Hexadecimal 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 field	Format	Description
result	Integer	Numerical 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
resultdesc	String	Result description
locator	Array of Objects	Array of locator objects identified by locator API key
locator.key.request	Object	Object of locator request status
locator.key.request.stat	Integer	Numerical 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.statdesc	String	Locator object status description
locator.key.notifications	Array of Objects	Array of notification objects
locator.key.notifications[n].id	String	Notification event unique identifier
locator.key.notifications[n].event	Hex	Hexadecimal 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].timestamp	YYYYmmddHHiiss	Notification event date and time
locator.key.notifications[n].params	Objects	Object of notification event parameters
locator.key.notifications[n].params.action	Integer	For 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.name	String	For 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.key	String	API key of the alert that triggered notification
locator.key.notifications[n].params.stat	Integer	Status of the alert that triggered notification
locator.key.notifications[n].geopoint	Objects	Object of geo point of the notification event
locator.key.notifications[n].geopoint.lat	Double	Latitude of the notification event
locator.key.notifications[n].geopoint.lng	Double	Longitude 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);    
        //..........
    }
}

API IKOL

Communication parties

Response time

Operation description

Character encoding

Auhentication

Query limitations

Locator API keys

User privileges

Functions

iaGetApiVersion

iaLoginSession

iaLogoutSession

iaGetUserLocators

iaGetUserInformation

iaGetLocatorTripDaysOfMonth

iaGetLocatorOdometer

iaGetLocatorInformation

iaGetLocatorTrips

iaGetLocatorLastTripDay

iaGetLocatorLastPosition

iaGetLocatorPosition

iaGetLocatorLastNotifications

iaGetLocatorNotifications

Examples of implementation

Getting locator information in PHP

Getting locator trips in Android Java