search_items

The search_items function is used to search for items by certain properties.

svc=core/search_items&params={
    "spec":{
        "itemsType":"<text>",
        "propName":"<text>",
        "propValueMask":"<text>",
        "sortType":"<text>",
        "propType":"<text>",
        "or_logic":<uint>
    },
    "force":<uint>,
    "flags":<long>,
    "from":<uint>,
    "to":<uint>
}

The request doesn’t check whether the itemsType, propName, propType, and sortType values exist. An unknown value doesn’t cause an error. For example, if itemsType contains an unknown item type, or no found item has the property specified in propName, the items array is empty. An unknown propType value is processed as property.

Flag values are specific to the item type. Values up to 0x80 are mostly the same for all types, but starting from 0x100 the same number selects different data. For example, 0x100 (256) returns advanced properties for avl_unit and drivers for avl_resource. A flag that doesn’t apply to the requested type is ignored without an error, and the response simply omits that data.

Item types (itemsType parameter):

• avl_resource: resource;
• avl_retranslator: retranslator;
• avl_unit: unit;
• avl_unit_group: unit group;
• user: user;
• avl_route: route.

To get the list of hardware types, use core/get_hw_types.

Item properties (propName and sortType parameters):

• sys_name: item name;
• sys_id: item ID;
• sys_unique_id: unique unit ID (IMEI);
• sys_phone_number: unit phone number;
• sys_phone_number2: unit second phone number;
• sys_user_creator: creator ID;
• rel_user_creator_name: creator name;
• sys_billing_account_guid: account ID;
• rel_billing_account_name: account name;
• rel_billing_parent_account_name: parent account name;
• rel_billing_plan_name: billing plan name;
• sys_comm_state: hardware state (1: enabled, 0: disabled);
• rel_hw_type_name: hardware name;
• rel_hw_type_id: hardware ID;
• sys_account_balance: account balance;
• sys_account_days: account days;
• sys_account_enable_parent: dealer rights (1: on, 0: off);
• sys_account_disabled: account blocked (1: yes, 0: no);
• rel_account_disabled_mod_time: last modification time for the sys_account_disabled properties, UNIX time;
• rel_account_units_usage: number of units in the account;
• rel_last_msg_date: last message time, UNIX time;
• rel_is_account: whether the resource is an account (1: yes, 0: no);
• login_date: last login time, UNIX time;
• retranslator_enabled: retranslator state (1: started, 0: stopped);
• rel_creation_time: creation time;
• rel_group_unit_count: the number of units in a group;
• rel_customfield_name: the name of the custom field of the item;
• rel_customfield_value: the value of the custom field of the item;
• rel_profilefield_name: the name of the profile field of the unit;
• rel_profilefield_value: the value of the profile field of the unit;
• rel_adminfield_name: the name of the admin field of the item;
• rel_adminfield_value: the value of the admin field of the item;
• rel_customfield_name_value: the name and value of the custom field of the item, separated by :;
• rel_profilefield_name_value: the name and value of the profile field of the unit, separated by :;
• rel_adminfield_name_value: the name and value of the admin field of the item, separated by :.

Custom and admin fields are available for units, unit groups, users, and resources. Profile fields are available only for units.

For more values of this parameter, see the table below.

Property types (propType parameter):

• property: property;
• list: list;
• propitemname: subitem name (for example, geofence is a subitem of resource);
• creatortree: chain of creators (search of this type will return the list of items the chain of creators of which contains the user specified in the propValueMask parameter);
• accounttree: chain of accounts (search of this type will return the list of items the chain of accounts of which contains the account specified in the propValueMask parameter);
• customfield: custom fields;
• profilefield: unit profile;
• adminfield: administrative fields;
• servicename: services.

If propType isn’t specified or has an unknown value, property is used.

If you want to search subitems, set the propitemname value for the propType parameter. Then, other parameters can have any of the following values:

By default, direct sorting works as follows:

• any name is split into bits for sorting (symbols, digits);
• digits are sorted first, and then symbols;
• - symbol is considered a hyphen and is sorted before digits (see the special sorting);
• system supports decimal mark numbers (3.12) and floating point numbers (2e10; 5.1E-2).

The following sorting types are available:

You can search for elements by several properties at once. For example:

"itemsType":"avl_resource","propName":"rel_is_account,*","propValueMask":"1,qwe","sortType":"sys_name","propType":"property,customfield"

The number of properties in the propName, propType and propValueMask parameters should be the same because they are calculated by three, respectively. The system doesn’t check this: if the numbers differ, no error is returned, but the search result may be different from what you expect.

The AND logic is used by default for the propName parameter. In the example above, the system finds all accounts (rel_is_account is 1) that have a custom field with the name or value qwe.

To enable the OR logic for the propName parameter, specify "or_logic":1 in the request.

In the propValueMask parameter, you can use the following comparison operators: <, >, =, >=, <=. If search criterion is a string field, the system will search for numbers only in the beginning of such value. If search criterion is number field, all value will be analysed.

"itemsType":"avl_unit","propName":"sys_name,sys_name","propValueMask":">=32,<33.5"

The search results list all units the names of which start with numbers between 32 and 33.5.

"itemsType":"avl_resource","propName":"sys_account_balance,sys_account_balance","propValueMask":">2,<=23"

The search results list all resources and accounts the balance of which is greater than 2 and less than or equal to 23.

You can also use the = operator if the field value starts with > or <.

"itemsType":"avl_unit","propName":"sys_name","propValueMask":"=>123<,=<123>"

The search results list all available units with the names >123< and <123>.

{
    "searchSpec": {                 /* search specification */
        "itemsType": "<text>",      /* items type */
        "propName": "<text>",       /* property name */
        "propValueMask": "<text>",  /* property value mask */
        "sortType": "<text>",       /* property name for sorting */
        "propType": "<text>",       /* property type */
        "or_logic": "<text>"        /* OR logic flag: "0" or "1" */
    },
    "dataFlags": <uint>,            /* applied data flags */
    "totalItemsCount": <uint>,      /* quantity of found items */
    "indexFrom": <uint>,            /* beginning index */
    "indexTo": <uint>,              /* ending index */
    "items": [{...}]                /* found items */
}

The indexTo value is the to value from the request, limited to the index of the last found item. If to is 0 in the request or no items are found, indexTo is 0.

The format of items array depends on the item type. All formats are described in the Data format section.

Possible error codes: