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

General information

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 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

  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.driver2 String

String 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.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);    
        //..........
    }
}