Child pages
  • cPanel API 2 - Filter and Sort Output
Skip to end of metadata
Go to start of metadata

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:

VariableTypeDescriptionPossible values
api2_filter BooleanWhether to enable filtering.
  • 1 — Enable filtering.
  • 0 — Disable filtering.
api2_filter_columnstringThe return to match against.The name of one of the function's returns.
api2_filter_termstringThe value to match.An integer or string value.
api2_filter_typestring

The match type.

  • If the api2_filter_term value is an integer, use a numeric operator.
  • If the api2_filter_term value is a string, use a string operator.

This variable defaults to contains.

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 can handle 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 can handle 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 undefined operators 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).

/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


Note:

 For more information, read our Calls from the WHM API documentation.

$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',
    ) 
);


Note:

For more information, read our Guide to the LiveAPI System.

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',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

<?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",
?> 


Warnings:

  • In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.
  • cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
  • For more information, read our Deprecated cPanel Tag Usage documentation.

uapi --user=username Email listpopswithdisk domain=example.com api2_filter=1 api2_filter_column=diskquota api2_filter_term=350 api2_filter_type=lt_handle_unlimited
{
  "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_0api_filter_column_0, and api_filter_term_0 variables.
  • 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 contain com with a quota that is greater than 100.

/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


Note:

 For more information, read our Calls from the WHM API documentation.

$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',
    ) 
);


Note:

For more information, read our Guide to the LiveAPI System.

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',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

cpapi2 --user=username Email listpopswithdisk domain=example.com api2_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
<?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",
?> 


Warnings:

  • In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.
  • cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
  • For more information, read our Deprecated cPanel Tag Usage documentation.

Sort output

cPanel API 2 sorting uses four basic variables:

VariableTypeDescriptionPossible values
api2_sort BooleanWhether to enable sorting.
  • 1 — Enable sorting.
  • 0 — Disable sorting.
api2_sort_columnstringThe output parameter to sort by.The name of one of the function's parameters.
api2_sort_methodstring

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_reverseBoolean

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.

/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


Note:

 For more information, read our Calls from the WHM API documentation.

$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',
    ) 
);


Note:

For more information, read our Guide to the LiveAPI System.

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',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

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


Warnings:

  • In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.
  • cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
  • For more information, read our Deprecated cPanel Tag Usage documentation.