SDK (Software Development Kit) is a set of tools for developing custom applications. Wialon SDK includes several APIs. The most basic of them is the Remote API, and these articles are focused on studying this exact tool. Remote API allows access to data through HTTP requests and is relevant for 1C, PHP, C++/C#, and other programming languages. JS API and others are built on top of the Remote API.

This article will cover the basic knowledge necessary for beginners to use Remote API.

Viewing Requests in the Browser

When starting to explore the SDK, it is often necessary to understand which API request is being sent to the server when performing a certain action in the Wialon interface. This can be easily tracked using built-in browser tools for network request monitoring.

In Chrome browser, you can do it using the Network tab in the Developer Tools, which can be opened by pressing F12. In other browsers, this tool may open differently, as described in the browser's documentation.

When viewing network requests, you can see the sent request, its parameters, and the response from the API server in JSON format.

Request Format

HTTP requests are sent to the server in the following format:

https://host/wialon/ajax.html?svc=REQUEST_NAME&params={PARAMETERS}&sid=SESSION_IDENTIFIER

Obtaining a Token and Authorization

Wialon uses a token for authorization, which is a key used for encrypted user identification.

To create a token, you can use the oAuth form. After you log in successfully, the token will be displayed in the browser's address bar as the value of the access_token parameter. It is important here to consider additional parameters that regulate properties such as token duration (duration parameter), user name (user parameter), token flags (access_type parameter), and others.

Example of an extended form for obtaining a token:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

Example of a response:

https://hosting.wialon.com/login.html?lang=en&user=USER_NAME&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=TOKEN_VALUE&svc_error=0

After obtaining the token, you can use it for authorization. Here is the example of logging in with a token:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login&params={"token":"TOKEN_VALUE"}

The response to the token login contains the eid parameter, and its value is the unique session identifier. It will be used in almost all API requests.

Setting the Time Zone

By default, when working with the Remote API, data is displayed according to the GMT+0 time zone. To change it to the desired time zone, the render/set_locale request is used. It is sufficient to execute this request within one active session.

When sending the render/set_locale request, you must use the tzOffset parameter. The standard method for calculating its value is described in the documentation.

You can also find out the required value of the tzOffset parameter by viewing network requests while changing the user's time zone in the web interface.

System ID

In the API, work with almost every item is done through system IDs, which are represented by unique numerical values.

System IDs are not displayed in web interfaces by default but they can be seen in three ways:

1. In the response to a request for searching items by property (core/search_items). We will explain it in more detail in the next section of this article.
   
2. In the parameters of requests when viewing network requests in the browser.

3. In the avl_id column in the management system.

   To make the avl_id column shown, you need to log in to the CMS and add ?features=avl_id to the end of the link. An example of such a link is shown in the image below.
   
   

Search Items by Property

This request allows you to find items by certain properties.

The search is performed for the following types of items, which are specified in the itemsType field:

• avl_hw — hardware type;
  
• avl_resource — resource;
  
• avl_retranslator — retranslator;
  
• avl_unit — unit;
  
• avl_unit_group — unit group;
  
• user — user;
  
• avl_route — route.
  

One of the possible search properties can be subitems. In this case, the propType parameter is set to propitemname, and the propName parameter takes the following values:

• units:
  
  • unit_sensors — sensors;
  • unit_commands — commands;
  • service_intervals — service intervals;
    
    
• resources:
  
  • drivers — drivers;
  • driver_groups — driver groups;
  • jobs — jobs;
  • notifications — notifications;
  • trailers — trailers;
  • trailer_groups — trailer groups;
  • zones_library — geofences;
  • reporttemplates — report templates;
  • orders — orders;
    
    
• routes:
  
  • rounds — rounds;
  • route_schedules — schedules;
    
    
• retranslators:
  
  • retranslator_units — retranslator units;
    
    
• units, users, or resources:
  
  • custom_fields — custom fields;
  • admin_fields — administrative fields.

The information in the response depends on the flags specified in the search request in the flags parameter. Flags are specified in DEC format.

Let's consider several examples of using the request for searching items by property (other examples can be found in the documentation).

Search Items by a Specific Name

In case you need to get a list of all units available to the user with the word Tractor in their name, as well as information about the sensors created in these units, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Search Users Created after a Specific Date

Imagine you need to get a list of users created after February 23, 2021, 05:41:46 (GMT+0). The response should contain user's system IDs and email addresses.

In such a case use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units of a Specific Type

Let’s get a list of units with the Wialon Retranslator hardware type that have sent messages after February 12, 2023, 12:00:00 (GMT+0). The response must display information about the sensors on the units, the last message date, and the position. In this case, use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units by Sensor Name

To get a list of units that have a sensor named Engine created, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Unit Groups by Multiple Properties

To get a list of unit groups created by User and containing more than 5 units, the following request can be used:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=SESSION_IDENTIFIER

List of Common Errors

An error is displayed when it is not possible to execute a request. A complete list of returned errors can be found in the documentation.

The most common errors are the following:

• {error: 1} — invalid session.
  This error is displayed when the unique session identifier has expired. To fix this error, simply log in with the token again and use the new session identifier (sid) for further requests.

  If within 5 minutes no request is made within the session, then it becomes inactive. To keep the session active, you can send an avl_evts request every 5 minutes.

• {error: 4} — invalid input.
  This error is displayed if there is a mistake in the request text, for example, not all required parameters are specified, text parameters are not enclosed in quotes, there is no opening or closing bracket, etc. To fix this error, correct the text of the executed request according to its description in the documentation.
  
  
• {error: 7} — access denied.
  This error is displayed if the user does not have sufficient access flags to execute the request. To fix this error, check if the token used to obtain the unique session identifier has sufficient access flags, as well as if the user the token was generated for has sufficient access rights regarding the used items.
  

Ekaterina Grib,Customer Service Engineer 2023-08-02