Item search

One of the most common requests in Wialon are search requests. Two kinds of search are possible in Wialon:

• Search item by ID,
• Search items by property.

Attention! To launch this example at Wialon Kit, change https://hst-api.wialon.com for https://kit-api.wialon.com in all requests and use user name and password of your account to login to the system or name and password of demo user kitdemo kitdemo.

The search by item ID is the simplest one. If item ID is known, any available information about this item can be fetched by using the request core/search_item. For example, you need to know the last location of a unit which ID is 34868. To get information about unit location, the flag 0x00000400 (1024) must be set. Besides, we will set the flag 0x00000001 (1) to get unit name. Detailed information about flags and data formats is given in the chapter Data format.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_item&
	params={
		"id":34868,
		"flags":1025
	}&sid=<your_sid>

Response:

{
    "item": {
        "nm": "Bavarian Tractor",
        "cls": 2,
        "id": 34868,
        "pos": {
            "t": 1358761631,
            "y": 53.9205504,
            "x": 27.4921152,
            "z": 238,
            "s": 0,
            "c": 102,
            "sc": 10
        },
        "lmsg": {
            "t": 1358761631,
            "f": 3,
            "tp": "ud",
            "pos": {
                "y": 53.9205504,
                "x": 27.4921152,
                "z": 238,
                "s": 0,
                "c": 102,
                "sc": 10
            },
            "i": 0,
            "p": {
                "param22": 3,
                "adc1": 12.352,
                "pwr_ext": 12.356,
                "param199": 0,
                "param241": 25701,
                "battery_charge": 0
            }
        },
        "uacl": 638138188323
    },
    "flags": 1025
}

From the response, we learn that unit with specified ID is called Bavarian Tractor and its last known position is 53.9205504 NL and 27.4921152 EL.

For more complicated searches, the request core/search_items is used. For example, all users can be found by making the following request:

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

Asterisk in the parameter propValueMask means that in the result array there will be users with any values in the field sys_name (that is users of any names). It means all available users will be present in the result. Value “1” of the parameter flags means that basic information about the item must be included in the result. Detailed information about user flags is given in the chapter Users. Zero values of the parameters from and to indicate that all found users should be returned.

Response:

{
    "searchSpec": {
        "itemsType": "user",
        "propName": "sys_name",
        "propValueMask": "*",
        "sortType": "sys_name"
    },
    "dataFlags": 1,
    "totalItemsCount": 1,
    "indexFrom": 0,
    "indexTo": 0,
    "items": [{
        "nm": "test_6512789",
        "cls": 1,
        "id": 648548,
        "uacl": -1
    }]
}

The example above fits only to search items like resources, retranslators, units, unit groups, users and routes. But some of those items such as resources or routes normally contain subitems, for example, geofences are subitems of resource. In case of search in subitems, you need to add one more parameter in search specification – propType – and set its value to “propitemname”, and in the parameter propName indicate subitem name. List of all subitems can be found in the chapter core/search_items.

As an example, let's examine situation in which we need to find resources which contain geofences with names containing the phrase “bing”. Let's say the returned result must contain only two first found resources. To have not only resources in the result but also geofences, the flag 0x00001000 (4096) must be set in addition to the basic flag.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&
	params={
		"spec":{
			"itemsType":"avl_resource",
			"propName":"zones_library",
			"propValueMask":"*bing*",
			"sortType":"zones_library",
			"propType":"propitemname"
		},
		"force":1,
		"flags":4097,
		"from":0,
		"to":1
	}&sid=<your_sid>

Response:

{
    "searchSpec": {
        "itemsType": "avl_resource",
        "propName": "zones_library",
        "propValueMask": "*bing*",
        "sortType": "zones_library",
        "propType": "propitemname"
    },
    "dataFlags": 4097,
    "totalItemsCount": 1,
    "indexFrom": 0,
    "indexTo": 0,
    "items": [{
        "nm": "template_ru",
        "cls": 3,
        "id": 163266,
        "zl": {
            "1": {
                "n": "Ветютнев",
                "d": "",
                "id": 1,
                "f": 1,
                "t": 2,
                "e": 60774,
                "b": {
                    "min_x": 43.5271002776,
                    "min_y": 49.7636455785,
                    "max_x": 43.5622908598,
                    "max_y": 49.7794993012,
                    "cen_x": 43.5446955687,
                    "cen_y": 49.7715724398
                }
            },
            "2": {
                "n": "Волгоград_конечный_пункт",
                "d": "",
                "id": 2,
                "f": 1,
                "t": 2,
                "e": 62438,
                "b": {
                    "min_x": 44.3872954375,
                    "min_y": 48.6329175554,
                    "max_x": 44.6300246245,
                    "max_y": 48.856592389,
                    "cen_x": 44.508660031,
                    "cen_y": 48.7447549722
                }
            },
            "3": {
                "n": "Михайловка_база",
                "d": "",
                "id": 3,
                "f": 1,
                "t": 2,
                "e": 4566,
                "b": {
                    "min_x": 43.107388,
                    "min_y": 50.009182,
                    "max_x": 43.294156,
                    "max_y": 50.119376,
                    "cen_x": 43.200772,
                    "cen_y": 50.064279
                }
            },
            "4": {
                "n": "Шмитовский",
                "d": "",
                "id": 4,
                "f": 1,
                "t": 1,
                "e": 39844,
                "b": {
                    "min_x": 37.5347102757,
                    "min_y": 55.7544919087,
                    "max_x": 37.5596537243,
                    "max_y": 55.7598140913,
                    "cen_x": 37.546216,
                    "cen_y": 55.757443
                }
            },
            "5": {
                "n": "bingo",
                "d": "",
                "id": 5,
                "f": 1,
                "t": 3,
                "e": 44015,
                "b": {
                    "min_x": 37.5537148786,
                    "min_y": 55.7585093867,
                    "max_x": 37.5576971214,
                    "max_y": 55.7607546133,
                    "cen_x": 37.555706,
                    "cen_y": 55.759632
                }
            }
        },
        "uacl": 2200454562339
    }]
}

As a result, one resource with 5 geofences was found. One of them contains bing in its name.

• Find units with name mask *Volvo*

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

spec : “itemsType”:“avl_unit” - Unit, “propName”:“sys_name” - search by name, “propValueMask”:“*Volvo*” - name mask

Result

{"searchSpec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Volvo awe*","sortType":"sys_name","propType":"","or_logic":"0"},"dataFlags":1439,"totalItemsCount":1,"indexFrom":0,"indexTo":0,"items":[{"nm":"Volvo awesome","cls":2,"id":21728414,"prp":{"label_color":"39219","solid_colors":"39219","track_solid":"39219","use_sensor_color":"0"},"crt":930848,"bact":930849,"mu":0,"ct":1599638776,"ftp":{"ch":0,"tp":0,"fl":1},"uid":"Volvo XC90","uid2":"","hw":96266,"ph":"+3758477844101","ph2":"","psw":"","pos":{"t":1614336759,"f":1073741831,"lc":0,"y":43.2444668333,"x":-118.146447667,"c":0,"z":300,"s":12,"sc":8},"lmsg":{"t":1614336759,"f":1073741831,"tp":"ud","pos":{"y":43.2444668333,"x":-118.146447667,"c":0,"z":300,"s":12,"sc":8},"i":0,"o":0,"lc":0,"rt":1614336760,"p":{"hdop":0.5,"pass":"E2000020340F02371900D866","mil":1001,"ves":"900025517477741444444","io_1_76":459,"tco_activity_tm":400,"fuel":220.79,"tco_driver1_id":"rettt"}},"act":1,"dactt":0,"flds":{"1":{"id":1,"n":"Type","v":"Navtelecom"},"2":{"id":2,"n":"Тип устройства","v":"Галилео"}},"fldsmax":-1,"aflds":{},"afldsmax":-1,"uri":"\/avl_library_image\/19725\/0\/library\/unit\/supertux.png","ugi":1,"uacl":-1}]}

• Get the list of sub-users

If hierarchy is simple - one parent account and other only his sub-users(account), it can be used simple criteria by [url=https://sdk.wialon.com/wiki/ru/sidebar/remoteapi/apiref/core/search_items#svojstva]rel_user_creator_name – creator name[/url].

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

If hierarchy is complicated, i.e Parent1 account - Sub-account1(Parent2) - Sub-account2 ….. - Sub-users, it needs to search by chain of creators - for «propType specify creatortree – chain of creators.

Every item has own creator, each creator has own creator and so on till top=user. So if there is user with id specified at “propValueMask” and creatortree ( “propType” ), a item (“itemsType”) will be included in response.

Example,“propValueMask” specify creator(user) ID on the high level, in this case it returns all sub-users (from all sub-accounts.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&sid=0281169f3adf2593e00f2fc1
params 
{"spec":{"itemsType":"user","propName":"sys_user_creator","propValueMask":930848,"sortType":"sys_name","propType":"creatortree"},"force":1,"flags":3,"from":0,"to":0}