cPanel API 2 - Filter and Sort Output - Knowledgebase

Introduction

You can use additional variables to filter and sort cPanel API 2 output.

Notes:

You can test cPanel API 2 functions in cPanel's API Shell interface (Home >> Advanced >> API Shell). Click Show Sort/Filter/Paginate Options to display the additional text boxes.
cPanel & WHM version 11.28 introduced this functionality.

Filter output

cPanel API 2 filters use four basic variables:

Variable	Type	Description	Possible values
api2_filter	Boolean	Whether to enable filtering.	1 — Enable filtering. 0 — Disable filtering.
api2_filter_column	string	The output parameter to match against.	The name of one of the function's parameters.
api2_filter_term	string	The value to match.	An integer or string value.
api2_filter_type	string	The match type. If the api2_filter_termvalue is an integer, use a numeric operator. If the api2_filter_termvalue is a string, use a string operator. This variable defaults tocontains.	Numeric operators: eq — The column equals to the match value. lt — The column is less than the match value. This match type cannot handle unlimited values. lt_handle_unlimited — The column is less than the match value. This match type canhandle unlimited values. gt — The column is greater than the match value. This match type cannot handle unlimited values. gt_handle_unlimited — The column is greater than the match value. This match type canhandle unlimited values. ne — The column does not equal the match value. Note: We introduced the ne operator in cPanel & WHM version 56. String operators: contains — The column contains the match value's string. Not case-sensitive. begins— The column begins with the match value's string. Not case-sensitive. ends— The column ends with the match value's string. Not case-sensitive. matches— The column matches the value as a regular expression. Other operators: defined — The column contains a value. undefined — The column does not contain a value. Note: We introduced the defined and undefinedoperators in cPanel & WHM version 58.

Examples

The following example function callsexecute the Email::listpopswithdisk function andfilter the results to return email accounts with disk quotas under 350 Megabytes (MB).

WHM API

/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&domain=example.com&api2_filter=1&api2_filter_column=diskquota&api2_filter_term=350&api2_filter_type=lt_handle_unlimited

Live API PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all example.com email addresses with quotas under 350MB.
$list_email_address_info = $cpanel->api2(
    'Email', 'listpopswithdisk', 
    array(
        'domain'                 => 'example.com',
        'api2_filter'            => '1',
        'api2_filter_column'     => 'diskquota',
        'api2_filter_term'       => '350',
        'api2_filter_type'       => 'lt_handle_unlimited',
    ) 
);

Live API Perl Class

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all example.com email addresses with quotas under 350MB.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    { 
        'domain'                 => 'example.com',
        'api2_filter'            => '1',
        'api2_filter_column'     => 'diskquota',
        'api2_filter_term'       => '350',
        'api2_filter_type'       => 'lt_handle_unlimited',
    }
);

cPanel Tag System (Depricated)

<?cp Email::listpopswithdisk (
          [strong]%[/strong] - %[br],
          email,
          diskquota
          )
          domain="example.com",
          api2_filter="1",
          api2_filter_column="diskquota",
          api2_filter_term="350",
          api2_filter_type="lt_handle_unlimited",
?>

Output (JSON)

{
  "cpanelresult": {
    "apiversion": 2,
    "records_before_filter": 6,
    "func": "listpopswithdisk",
    "data": [
      {
        "txtdiskquota": "unlimited",
        "diskquota": "unlimited",
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "None",
        "_diskused": "483",
        "login": "user1@example.com",
        "email": "user1@example.com",
        "domain": "example.com",
        "user": "user1",
        "humandiskused": "483\u00a0bytes",
        "diskusedpercent20": 0,
        "_diskquota": 0
      },
      {
        "txtdiskquota": "unlimited",
        "diskquota": "unlimited",
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "None",
        "_diskused": "0",
        "login": "user2@example.com",
        "email": "user2@example.com",
        "domain": "example.com",
        "user": "user2",
        "humandiskused": "None",
        "diskusedpercent20": 0,
        "_diskquota": 0
      },
      {
        "txtdiskquota": 325,
        "diskquota": 325,
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "325\u00a0MB",
        "_diskused": "0",
        "login": "user3@example.com",
        "email": "user3@example.com",
        "domain": "example.com",
        "user": "user3",
        "humandiskused": "None",
        "diskusedpercent20": 0,
        "_diskquota": "340787200"
      },
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
}

Use multiple filters

To use multiple filters on a single cPanel API 2 call, append an underscore (_) and a number to the end of each filter variable.

For example, use the following variables to pass two sets of filter information:

Pass the first set of filter information to the api2_filter_type_0, api_filter_column_0, and api_filter_term_0variables.
Pass the second set of filter information to the api2_filter_type_1 , api_filter_column_1 , and api_filter_term_1 variables.

Note:

Do not include more than one api2_filter boolean variable.

For example, the following examples filter the Email::listpopswithdisk function's output to email addresses that containcom with a quota that is greater than 100.

WHM API

/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&domain=example.comapi2_filter=1&api2_filter_type_0=gt_handle_unlimited&api2_filter_column_0=quota&api2_filter_term_0=100&api2_filter_type_1=contains&api2_filter_column_1=email&api2_filter_term_1=com

LIVEAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all .com email addresses with quotas over 100MB.
$list_email_address_info = $cpanel->api2(
    'Email', 'listpopswithdisk', 
    array(
        'api2_filter'            => '1',
        'api2_filter_column_0'   => 'diskquota',
        'api2_filter_term_0'     => '100',
        'api2_filter_type_0'     => 'gt_handle_unlimited',
        'api2_filter_column_1'   => 'email',
        'api2_filter_term_1'     => 'com',
        'api2_filter_type_1'     => 'contains',
    ) 
);

LIVEAPI Perl Class

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all .com email addresses with quotas over 100MB.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    { 
        'api2_filter'            => '1',
        'api2_filter_column_0'   => 'diskquota',
        'api2_filter_term_0'     => '100',
        'api2_filter_type_0'     => 'gt_handle_unlimited',
        'api2_filter_column_1'   => 'email',
        'api2_filter_term_1'     => 'com',
        'api2_filter_type_1'     => 'contains',
    }
);

cPanel Tag System (Depricated)

<?cp Email::listpopswithdisk (
          [strong]%[/strong] - %[br],
          email,
          diskquota
          )
          domain="example.com",
          api2_filter="1",
          api2_filter_column_0="diskquota",
          api2_filter_term_0="100",
          api2_filter_type_0="gt_handle_unlimited",
          api2_filter_column_1="email",
          api2_filter_term_1="com",
          api2_filter_type_1="contains",
?>

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use theLiveAPI system to call the cPanel APIs.

cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read ourDeprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.

Sort output

cPanel API 2 sorting uses four basic variables:

Variable	Type	Description	Possible values
api2_sort	boolean	Whether to enable sorting.	1 — Enable sorting. 0 — Disable sorting.
api2_sort_column	string	The output parameter to sort by.	The name of one of the function's parameters.
api2_sort_method	string	The type of sorting to use. This variable defaults to lexicographic. Warning: You must set this parameter whenever you sort numeric values, or the function will fail.	ipv4 — Sort output by the numeric value of each octet in an IPv4 address. numeric — Sort output in numeric order, with 0 as the lowest number. numeric_zero_as_max — Sort output in numeric order, with 0 as the highest number. lexicographic — Sort output in alphabetical order.
api2_sort_reverse	boolean	Whether to sort data in reverse order.	1 — Sort in reverse order. 0 — Do not sort in reverse order.

Examples

The following example function callsexecute the Stats::lastvisitors function and use the ipv4 method to sort the ip parameter's values in reverse order.

WHM API

/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Stats&cpanel_jsonapi_func=lastvisitors&domain=example.com&api2_sort=1&api2_sort_column=ip&api2_sort_method=ipv4&api2_sort_reverse=1

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List recent visitors, sorted by IP address in reverse order.
$sorted_visitors = $cpanel->api2(
    'Stats', 'lastvisitors', 
    array(
        'domain'                 => 'example.com',
        'api2_sort'              => '1',
        'api2_sort_column'       => 'ip',
        'api2_sort_method'       => 'ipv4',
        'api2_sort_reverse'      => '1',
    ) 
);

LiveAPI Perl Class

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List recent visitors, sorted by IP address in reverse order.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    { 
        'domain'                 => 'example.com',
        'api2_sort'              => '1',
        'api2_sort_column'       => 'ip',
        'api2_sort_method'       => 'ipv4',
        'api2_sort_reverse'      => '1',
    }
);

cPanel Tag System (Depricated)

<?cp Email::listpopswithdisk (
          %[br],
          ip
          )
          domain="example.com",
          api2_sort="1",
          api2_sort_column="ip",
          api2_sort_method="ipv4",
          api2_sort_reverse="1",
?>

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use theLiveAPI system to call the cPanel APIs.

Knowledgebase

Categories

Categories