Advertiser API- Filtering, Sorting, and Paging

Filtering

Parameters of the Filter type allow the caller of an API method to restrict the results returned by the method to those which meet certain criteria. Fields that can be filtered are limited to those of the model whose type the function returns.

The default operator for filters is an equality filter that limits results to those models with a field matching a single value or one of a list of values. For example, if you wish to retrieve Offers whose status are "active" and whose currency is "USD", you can use the following filters:

&filters[status]=active&filters[currency]=USD

The default operator supports an array of values to achieve the effect of "is one of", so we can update our example to return Offers whose statuses are "paused" in addition to those that are "active" by using the parameter array notation "[]" to denote a list of statuses:

&filters[status][]=active&filters[status][]=paused&filters[currency]=USD

The default behavior for filters is to "AND" the conditions together, so that results meet the criteria of every filter. It's also possible to construct a filter that "OR"s the conditions together. For example, if you wish to retrieve Offers whose status are "active" OR whose currency are "USD", you can construct a filter by prefixing each field with an "[OR]" block:

&filters[OR][status]=active&filters[OR][currency]=USD

In addition to the default equality operator, the following are additional comparison operators that can be used to limit results with a filter. Note that these are limited to comparing against a single value, rather than a list like the default operator.

• NOT_EQUAL_TO - Finds objects which do not have the provided value. Example: Retrieve Offers whose status is not equal to "active"

  &filters[status][NOT_EQUAL_TO]=active

• LESS_THAN - Finds objects which have a value less than the provided value. Example: Retrieve Offers whose id is less than 25

  &filters[id][LESS_THAN]=25

• LESS_THAN_OR_EQUAL_TO - Finds objects which have a value less than or equal to the provided value. Example: Retrieve Offers whose id is less than or equal to 25

  &filters[id][LESS_THAN_OR_EQUAL_TO]=25

• GREATER_THAN - Finds objects which have a value greater than the provided value. Example: Retrieve Offers whose id is greater 25

  &filters[id][GREATER_THAN]=25

• GREATER_THAN_OR_EQUAL_TO - Finds objects which have a value greater than or equal to the provided value. Example: Retrieve Offers whose id is greater than or equal to 25

  &filters[id][GREATER_THAN_OR_EQUAL_TO]=25

• LIKE - Returns objects which have a value that matches the provided string, using case-insensitive search. The '%' character is a wildcard: use at the beginning of the string to find values ending in that string, at the end of the string to find values beginning with that string, or in the middle to find values bookended by two parts of the string. Example: Retrieve Offers whose names begin with "Atomic Tilt", such as "Atomic Tilt (iPhone/US)" or "Atomic Tilt (Android/SK)"

  &filters[name][LIKE]=Atomic Tilt%

  Example: Retrieve Offers whose names have "gift card" in them, such as "$1,500 Mondo Burger Gift Card" or "Mother's Day Flowers $500 Gift Card (Incent)"

  &filters[name][LIKE]=%gift card%

  Important: If you don't use a wildcard, the call only returns values that match the provided string, though still as a case-insensitive search.

• NOT_LIKE - Returns objects which have a value that does not match the provided string. The '%' character is a wildcard, with the same function as in the LIKE operator. Example: Retrieve Offers whose name does not contain "Free"

  &filters[name][NOT_LIKE]=%Free%

• NULL - Finds objects which have a value that is NULL. This is not the same as an empty string; you should use the EQUAL_TO conditional to find objects whose value is an empty string. Example: Retrieve Offers whose description is NULL

  &filters[description][NULL]=1

• NOT_NULL - Finds objects which have a value that is NOT NULL. This is not the same as an empty string; you should use the NOT_EQUAL_TO conditional to find objects whose value is an not an empty string. Example: Retrieve Offers whose description is NOT NULL.

  &filters[description][NOT_NULL]=1

• TRUE - Finds objects which have a value that is the boolean true. Example: Retrieve Offers which are private

  &filters[is_private][TRUE]=1

• FALSE - Finds objects which have a value that is the boolean false. Example: Retrieve Offers which are not private

  &filters[is_private][FALSE]=1

Report Filtering

Parameters of the Report Filter type are similar to the Filter type except that they are used exclusively when calling functions that generate reports. The format for a Report Filter is slightly different than that of normal Filter parameters in a few ways. The conditional must always be specified using a "conditional" index. For conditionals that take value parameters, the values are specified as siblings of the conditional, indexed by the string "values". Additionally, some of the available conditionals differ between the two filter types. Report Filters do not support the "OR" construct of regular filters; instead, all provided filters are "AND"ed together.

The "EQUAL_TO" conditional behaves like an IN clause, allowing you to filter for data where the field matches one of the provided values. For example, if you are applying filters to a Conversion Report and you wish to restrict the results to conversions having either an "active" or a "pending" status, you would format the report filters as follows:

&filters[status][conditional]=EQUAL_TO&filters[status][values][0]=active&filters[status][values][1]=pending

In addition to the "EQUAL_TO" operator, following are additional comparison operators that can be used to limit results with a Report Filter.

• BETWEEN - Finds objects which have a field that is in a certain range, inclusive. Example: Retrieve conversions whose date is greater than or equal to 2013-12-29 and less than or equal to 2014-01-03

  &filters[Stat.date][conditional]=BETWEEN&filters[Stat.date][values][0]=2013-12-29&filters[Stat.date][values][1]=2014-01-03

• NOT_EQUAL_TO - Finds objects which do not have the provided value. Example: Retrieve conversions whose status is not equal to "active"

  &filters[Stat.conversion_status][conditional]=NOT_EQUAL_TO&filters[Stat.conversion_status][values]=active

• LESS_THAN - Finds objects which have a value less than the provided value. Example: Retrieve conversions whose id is less than 25

  &filters[Stat.id][conditional]=LESS_THAN&filters[Stat.id][values]=25

• LESS_THAN_OR_EQUAL_TO - Finds objects which have a value less than or equal to the provided value. Example: Retrieve conversions whose id is less than or equal to 25

  &filters[Stat.id][conditional]=LESS_THAN_OR_EQUAL_TO&filters[Stat.id][values]=25

• GREATER_THAN - Finds objects which have a value greater than the provided value. Example: Retrieve conversions whose id is greater 25

  &filters[Stat.id][conditional]=GREATER_THAN&filters[Stat.id][values]=25

• GREATER_THAN_OR_EQUAL_TO - Finds objects which have a value greater than or equal to the provided value. Example: Retrieve conversions whose id is greater than or equal to 25

  &filters[Stat.id][conditional]=GREATER_THAN_OR_EQUAL_TO&filters[Stat.id][values]=25

• LIKE - Returns objects which have a value that matches the provided string, using case-insensitive search. The '%' character is a wildcard: use at the beginning of the string to find values ending in that string, at the end of the string to find values beginning with that string, or in the middle to find values bookended by two parts of the string. Example: Retrieve Conversions for Offers whose names begin with "Atomic Tilt", such as "Atomic Tilt (iPhone/US)" or "Atomic Tilt (Android/SK)"

  &filters[Offer.name][conditional]=LIKE&[Offer.name][values]=Atomic Tilt%

  Example: Retrieve Conversions for Offers whose names have "gift card" in them, such as "$1,500 Mondo Burger Gift Card" or "Mother's Day Flowers $500 Gift Card (Incent)"

  &filters[Offer.name][conditional]=LIKE&[Offer.name][values]=%gift card%

  Important: If you don't use a wildcard, the call only returns values that match the provided string, though still as a case-insensitive search.

• NOT_LIKE - Returns objects which have a value that does not match the provided string. The '%' character is a wildcard, with the same function as in the LIKE operator. Example: Retrieve Conversions for Offers whose names do not contain "Free"

  &filters[Offer.name][conditional]=NOT_LIKE&[Offer.name][values]=%Free%

• NULL - Finds objects which have a value that is NULL. This is not the same as an empty string; you should use the EQUAL_TO conditional to find objects whose value is an empty string. Notice no "values" are passed for this conditional. Example: Retrieve conversions whose ip is NULL

  &filters[Stat.ip][conditional]=NULL

• NOT_NULL - Finds objects which have a value that is NOT NULL. This is not the same as an empty string; you should use the NOT_EQUAL_TO conditional to find objects whose value is an not an empty string. Notice no "values" are passed for this conditional. Example: Retrieve conversions whose ip is NOT NULL.

  &filters[Stat.ip][conditional]=NOT_NULL

Note: Since the Report Filter does not support "TRUE" or "FALSE" conditionals, use the "EQUAL_TO" or "NOT_EQUAL_TO" conditionals instead when filtering on boolean-typed report fields. A value of "1" corresponds to boolean true, while a value of "0" corresponds to boolean false.

Sorting

Parameters of the Sort type are used on get/find type functions to order the results returned by the method. The fields that can be sorted are limited to those of the model whose type the function returns. The format of a sort parameter is an object having keys identifying the model field name and values specifying the direction of either "asc" or "desc" to order the results in ascending order or descending order, respectively.

For example, an API method that has a sort parameter and returns Offer model objects could be called in the following way to sort the results by Offer.status ascending and by Offer.id descending within each status:

&sort[status]=asc&sort[id]=desc

Paging

API calls with limit and page parameters allow you to control the amount of data returned in that call. To handle paging, include both parameters: limit for the size of the result set and page for which result set to return.

limit must be an integer, and must be supplied to return paged results. page must be an integer, and defaults to 1 if omitted. For example, to return the first 50 results you would append the following to your call:

&limit=50

To return the second set of 50 results, append:

&limit=50&page=2

Note: If you supply only the page parameter, you may receive unexpected results. Do not supply page without also supplying limit.

When using paging, the data portion of the response object changes to contain the paging information and subset of records. The structure changes to:

The fields contained:

• page: page of the result set returned
• current: index of the first row on this page; this is based on the total result set given the parameters supplied, not the first record's ID
• count: total number of records available given the parameters supplied
• pageCount: total number of pages given the parameters supplied
• data: result set of that page, structured as the data object normally is without paging active

Note: In some methods, some of these fields may not appear.