u-Slicer Knowledge Base : APIv2 Specification

audience method

• Description:
• Returns audience data restricted by query parameters passed in POST arguments. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/audience
• URL arguments:
• None
• POST arguments (required unless marked optional):
  • audience_key (optional): the name of the audience source. The default value is the first available audience source.
  • audience_rows_limit (optional): the maximum number of rows to be processed (the greater the number, the higher the precision). By default API requests process 1,000,000 rows and UI-originated requests process 10,000 rows. The minimum value is 10,000. The maximum value is 10,000,000.
    
  • filters (optional): an array with the following structure:
    • "name": "key_field",
    • "case_insensitive": (optional), defines whether search should be case-insensitive. Possible values: (1 - case-insensitive, 0 - case-sensitive). The default value is 0.
    • "search_mappings": (optional), defines whether the search should be performed in mappings. Possible values: (1 - search should be performed in both key field values and their mappings, 0 - search should be performed in key field values only). The default value is 0.
    • "value": ["value1", ... ],
    • "match": "equals|not equals|contains|not contains|beginswith|endswith|not beginswith|not endswith"

    where the value of the "value" field should be an array.

    If "search_mappings" is set to 1, the search will be performed for both specified key field values and their mappings (descriptions). For example, if you have the  creative_id  key field with some value of "1" and its mapping of "First Creative", you can search for it as follows:

    {"name": "creative_id", "value": ["First Creative"],"match":"equals", "search_mappings": 1} 
    
    OR 
    
    {"name": "creative_id", "value": [1],"match": "equals"} 

    Search results will be fully identical. 

    You can even use a partial matching, like {"name":"creative_id","value": ["Creative"],"match":" contains", "search_mappings": 1}, but please note that if you use a too short search string (1 - 2 characters long), it may take significant time to look up all matching records.

• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• split_by: an array of the key fields to split data by in the form of ["key_field1",...].
• start_date: the start of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• end_date: the end of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• timezone (optional):  time zone UTC offset in hours. Format: N, where N - any integer in the range of -12 <= N <= +12. 

• Output:
• status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields only. Possible values:
  • success: the request was processed successfully.
  • bad_request: invalid request parameters, please see the reason field for more details.
  • timeout: the request took too long to complete.
  • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
  • internal_error: the request failed due to an unknown problem.
• reason: user-friendly description of the occurred error. This field is displayed for failed requests only.
• total: this section contains information about the entire dataset returned by the query.
  • data: the summary values for each data column found in the result dataset. It's an array of elements with the following fields:
    • name: data field name.
    • value: data field value.
  • records_found: the total number of found records.
  • confidence_range: the confidence range for data (percent), presented in this section if the returned dataset is compressed. Available for the total rows.
  • dates: the array with all the dates, for which data exist in the period from the start_date to the end_date .
• rows: this section contains query data results. It is an array of data rows, each containing the following fields.
  • data: the list of items with field name and field value:
    • name: data field name.
    • value: data field value.
    • percent: percent of the total value (if applicable).
  • name: the value of the split_by key field for this row, including six specific time-related fields:

• • • • granularity_hour: data, aggregated by day+hour, where each key field value contains 1 item (date and hour) like:
        "name": [ "2013-09-30 19:00" ]
      • granularity_day: data, aggregated by day, where each key field value contains 1 item (date) like:
        "name": "2013-09-30"
      • granularity_week: data, aggregated by week, where each key field value contains 1 item (week) like:
        "name": "2013-W48"
      • granularity_month: data aggregated by month, where each key field value contains 1 item (month) like:
        name": "2013-09"
      • granularity_quarter: data aggregated by quarter, where each key field value contains 1 item (quarter) like:
        name": "2013 Q4"
      • granularity_year: data aggregated by year, where each key field value contains 1 item (year) like:
        name": "2013"

Note 1: If the split_by POST argument contains several key fields, then the name parameter also contains several key fields.

• • • confidence_range: the confidence range for data (percent), presented in this section if the returned dataset is compressed. Available for every data row in the resulting dataset.

delete_calc_mappings method

• Description:
  • Deletes the calculation mapping specified by the name POST argument. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/delete_calc_mappings   

• URL arguments:
• None
• POST arguments (required unless marked optional):
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• name: mapping name.
• Output:
  • status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields only. Possible values:
    • success: the request was processed successfully.
    • bad_request: invalid request parameters, please see the reason field for more details.
    • timeout: the request took too long to complete.
    • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
    • internal_error: the request failed due to an unknown problem.
  • reason: user-friendly description of the occurred error. This field is displayed for failed requests only.

delete_column method

• Description:
  • Deletes the user-defined data column specified by the name POST argument. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/delete_column  

• URL arguments:
• None
• POST arguments (required unless marked optional):
• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• name: the name of the user-defined data column to be deleted.
• Output:
• status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields only. Possible values:
  • success: the request was processed successfully.
  • bad_request: invalid request parameters, please see the reason field for more details.
  • timeout: the request took too long to complete.
  • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
  • internal_error: the request failed due to an unknown problem.
• reason: user-friendly description of the occurred error. This field is displayed for failed requests only.

export method

• Description:
  • Exports report data to a file of the xlsx, csv, or tsv format. Data is restricted by query parameters passed in POST arguments. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/export   

• URL arguments:
• None
• POST arguments (required unless marked optional):
• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• split_by: an array of the key fields to split data by in the form of ["key_field1",...].
• include_mappings (optional): defines whether key field value mappings are returned by the API request. The default value is 1 (mappings are returned) if only 1 key field is used in the  split_by POST argument. The default value is 0 (mappings are not returned) if 2 or more key fields are used in the split_by POST argument.
• include_total (optional): defines whether to display Total values in the exported file. Possible values: (0 - don't display Total values in the exported file, 1 - display Total values in the exported file). The default value is 0.
• start_date: the start of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• end_date: the end of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• timezone (optional): time zone UTC offset in hours. Format: N, where N - any integer in the range of -12 <= N <= +12.
• export_format: target file format: xlsx, csv, or tsv.
  
• filters (optional): an array with the following structure:
  • "name": "key_field",
  • "case_insensitive": (optional), defines whether search should be case-insensitive. Possible values: (1 - case-insensitive, 0 - case-sensitive). The default value is 0.
  • "search_mappings": (optional), defines whether the search should be performed in mappings. Possible values: (1 - search should be performed in both key field values and their mappings, 0 - search should be performed in key field values only). The default value is 0.
  • "value": ["value1", ... ],
  • "match": "equals|not equals|contains|not contains|beginswith|endswith|not beginswith|not endswith"

  where the value of the "value" field should be an array.

  If "search_mappings" is set to 1, the search will be performed for both specified key field values and their mappings (descriptions). For example, if you have the  creative_id  key field with some value of "1" and its mapping of "First Creative", you can search for it as follows:

  {"name": "creative_id", "value": ["First Creative"],"match":"equals", "search_mappings": 1} 
  
  OR 
  
  {"name": "creative_id", "value": [1],"match": "equals"} 

  Search results will be fully identical. 

  You can even use a partial matching, like {"name":"creative_id","value": ["Creative"],"match":" contains", "search_mappings": 1}, but please note that if you use a too short search string (1 - 2 characters long), it may take significant time to look up all matching records.

• • data_filters (optional): an array with the following structure:
    • "name": "data_field",
    • "value": "value1",
    • "match": "<|>|<=|>=”

    where the "value" field is just one value. The "match" can be "<" for less than value, ">" for greater than value, "<=" for less than or equal to value, or ">=" for greater than or equal to value. 

    If a data_field is in percent format, its value should also be divided by one hundred (30% becomes 0.3). Note, that this behavior is different in API and UI.

• • filter_template (optional): a string template defining priorities for filters specified in the filters POST argument. Can contain the following elements:
    • opening/closing parentheses
    • OR/AND operators
    • "x" character as a placeholder for filters

    Example: "x OR (x AND x)".

    Filters from the filters POST argument in the specified order are substituted instead of x.

• • data_filter_template (optional): a string template defining priorities for filters specified in the data_filters POST argument. Can contain the following elements:
    • opening/closing parentheses
    • OR/AND operators
    • "x" character as a placeholder for filters

    Example: "x OR (x AND x)".

    Filters from the  data_filters  POST argument in the specified order are substituted instead of x.

• order_by (optional): defines sorting rules. A single record or an array of records with the following structure:
  • "name": "field", the name of the key or data field to sort the results by. Note that this field can be any key field, specified in the split_by POST argument, or one of the data fields specified by the data_fields POST argument (or any of the data fields if the  data_fields POST argument is not specified). The default value is the first column with enabled percent.
  • "mapping": defines whether to sort by key field ID or by key field mapping. Possible values: (0 - sort by key field ID, 1 - sort by key field mapping). The default value is 0.
  • "direction": sort in the ascending or descending order, either ASC or DESC. The default value is DESC.

• • data_fields (optional): the array of data fields to be returned in the form of [ "data_field1", .... ]. If it is not defined (by default), data fields will not be returned. To receive the details of all data fields available for your particular report use the info method.

• xlsx file with exported report data (column headers and data rows). Maximum 1048570 matching data rows are exported.

• csv file with exported report data (column headers and data rows). Maximum 1000000 matching data rows are exported. If the total number of data rows to be exported exceeds 1000000, then the Others data row is added: the summary of data rows beyond 1000000.

• tsv file with exported report data (column headers and data rows). The escape character is "". Maximum 1000000 matching data rows are exported. If the total number of data rows to be exported exceeds 1000000, then the Others data row is added: the summary of data rows beyond 1000000.

get_mappings method

• Description:
  • Matches identifiers to mappings for a particular key field. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/get_mappings

• URL arguments:
• None
• POST arguments (required unless marked optional):
• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
•   search_mappings: an array with the following structure:
  • [ {"key": "key_field",
  • "values": ["value1", ... ]},...],

where "values" is an array of key field identifiers to search mappings for, and "key_field" is the name of the key field.

• Output:
  • status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the  status and reason fields only. Possible values:
    • success: the request was processed successfully.
    • bad_request: invalid request parameters, please see the reason field for more details.
    • timeout: the request took too long to complete.
    • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
    • internal_error: the request failed due to an unknown problem.
  • reason: user-friendly description of the occurred error. This field is displayed for failed requests only.
  • mappings: a list of key field value /  key field value mapping pairs with the following structure:
    • {"key_field": 
    • {"value1: "mapping1",...},...}

google_export method

• Description:
  • Exports report data to Google Sheets. Data is restricted by query parameters passed in POST arguments. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/google_export

• URL arguments:
• None
• POST arguments (required unless marked optional):
• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• split_by: an array of the key fields to split data by in the form of ["key_field1",...].
• include_mappings (optional): defines whether key field value mappings are returned by the API request. The default value is 1 (mappings are returned) if only 1 key field is used in the split_by POST argument. The default value is 0 (mappings are not returned) if 2 or more key fields are used in the split_by POST argument.
• email: an array of 1 - 20 email addresses in the form of ["email_address1",...] .
• start_date: the start of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• end_date: the end of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• timezone (optional): time zone UTC offset in hours. Format: N, where N - any integer in the range of -12 <= N <= +12.
• filters (optional): an array with the following structure:
  • "name": "key_field",
  • "case_insensitive": (optional), defines whether search should be case-insensitive. Possible values: (1 - case-insensitive, 0 - case-sensitive). The default value is 0.
  • "search_mappings": (optional), defines whether the search should be performed in mappings. Possible values: (1 - search should be performed in both key field values and their mappings, 0 - search should be performed in key field values only). The default value is 0.
  • "value": ["value1", ... ],
  • "match": "equals|not equals|contains|not contains|beginswith|endswith|not beginswith|not endswith"

  where the value of the "value" field should be an array.

  If "search_mappings" is set to 1, the search will be performed for both specified key field values and their mappings (descriptions). For example, if you have the  creative_id  key field with some value of "1" and its mapping of "First Creative", you can search for it as follows:

  {"name": "creative_id", "value": ["First Creative"],"match":"equals", "search_mappings": 1} 
  
  OR 
  
  {"name": "creative_id", "value": [1],"match": "equals"} 

  Search results will be fully identical. 

  You can even use a partial matching, like {"name":"creative_id","value": ["Creative"],"match":" contains", "search_mappings": 1}, but please note that if you use a too short search string (1 - 2 characters long), it may take significant time to look up all matching records.

• • data_filters (optional): an array with the following structure:
    • "name": "data_field",
    • "value": "value1",
    • "match": "<|>|<=|>=”

    where the "value" field is just one value. The "match" can be "<" for less than value, ">" for greater than value, "<=" for less than or equal to value, or ">=" for greater than or equal to value. 

    If a data_field is in percent format, its value should also be divided by one hundred (30% becomes 0.3). Note, that this behavior is different in API and UI.

• • filter_template (optional): a string template defining priorities for filters specified in the filters POST argument. Can contain the following elements:
    • opening/closing parentheses
    • OR/AND operators
    • "x" character as a placeholder for filters

    Example: "x OR (x AND x)".

    Filters from the filters POST argument in the specified order are substituted instead of x.

• • data_filter_template (optional): a string template defining priorities for filters specified in the data_filters POST argument. Can contain the following elements:
    • opening/closing parentheses
    • OR/AND operators
    • "x" character as a placeholder for filters

    Example: "x OR (x AND x)".

    Filters from the  data_filters  POST argument in the specified order are substituted instead of x.

• order_by  (optional): defines sorting rules. A single record or an array of records with the following structure:
  • "name": "field", the name of the key or data field to sort the results by. Note that this field can be any key field, specified in the split_by POST argument, or one of the data fields specified by the data_fields POST argument (or any of the data fields if the  data_fields POST argument is not specified). The default value is the first column with enabled percent.
  • "mapping": defines whether to sort by key field ID or by key field mapping. Possible values: (0 - sort by key field ID, 1 - sort by key field mapping). The default value is 0.
  • "direction": sort in the ascending or descending order, either ASC or DESC. The default value is DESC.

• • data_fields (optional): the array of data fields to be returned in the form of [ "data_field1", .... ]. If it is not defined (by default), data fields will not be returned. To receive the details of all data fields available for your particular report use the info method.

  Output:

• status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields. Possible values:
  • success: the request was processed successfully.
  • bad_request: invalid request parameters, please see the reason field for more details.
  • timeout: the request took too long to complete.
  • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
  • internal_error: the request failed due to an unknown problem.
• reason: user-friendly description of the occurred error. This field is displayed for failed requests only.
• Google Sheets file: a file with exported report data (column headers and data rows). Maximum 300000 data rows.

info method

• Description:
  • Provides information about a particular slicer. This information includes the list of available key and data fields, as well as their descriptions. See example.
• URL:
  • https://uslicer.iponweb.com/API/v2/info

• URL arguments:
• None
• POST arguments (required unless marked optional):
• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• Output:
  • status: the status of the request. success , if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields only. Possible values:
    • success: the request was processed successfully.
    • bad_request: invalid request parameters, please see the reason field for more details.
    • timeout: the request took too long to complete.
    • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
    • internal_error: the request failed due to an unknown problem.
  • reason: user-friendly description of the occurred error. This field is displayed for failed requests only.
  • annotation: slicer annotation. Possible values:
    
    • null (if no annotation exists for the slicer specified by the slicer_name POST argument).
    • annotation text (if any annotation exists for the slicer specified by the slicer_name POST argument).
      

• • key_fields: the list of key fields available for the report specified by the project_name and slicer_name POST arguments.
    • name: key field name.
    • aliases: the list of all aliases for the key field name.
    • description: key field full name.
    • type: key field type. Possible values: int and text
    • mapping: key field mapping or null (if key field mapping doesn't exist).
    • is_segmented: key field segmentation sign. Possible values: 
      • 1: the field is segmented.
      • 0: the field is not segmented.
  • data_fields: the list of data fields available for the report specified by the project_name and slicer_name POST arguments.
    • name: data field name.
    • aliases: the list of all aliases for the data field name.
    • description: data field full name.
    • type: data field type, either int, float, or percent
    • display_precision: default precision for visual display.
    • is_optional: defines data field display importance. Possible values: 1 - data field display is optional (the data field is not displayed in UI when the Slicer is initially opened, but it can be added later), 0 - data field display is required (the data field is displayed in UI when the Slicer is initially opened).
    • show_percent: defines whether to show percent column in the user interface. Possible values: 0 - don’t show percent, 1 - show percent only when sorting by the field, 2 - always show percent.
    • formula: data field formula. Possible values:
      • null for common data fields.
      • data field calculation logic for derived fields.
        
    • formula_description: data field formula description. Possible values:
      • null for common data fields.
      • data field formula description for derived data fields.
    • access: access permission. Possible values: null / shared / private. null value is set for common data fields only. shared / private values are set for custom data fields only. shared value means that the custom data column is available for all users.  private value means that the custom data column is available for its creator only.
    • display_pattern: display pattern for the data column. Possible values: null for common data columns and any_characters{}any_characters for custom data columns, where {} represents custom data column value.
  • timezone: default slicer time zone.
  • supports_timezone: time zone support sign. Possible values:
    • 1: time zone is supported.
      
    • 0: time zone is not supported.
      
  • first_date: the first date with available data for the slicer specified by the slicer_name POST argument. Format: YYYY-MM-DD.
  • last_date: the last date with available data for the slicer specified by the slicer_name POST argument. Format: YYYY-MM-DD.
  • additional_info: the dictionary with additional information about the slicer specified by the project_name and slicer_name POST arguments.  
    • slicer_id: the id of the slicer specified by the project_name and slicer_name POST arguments.
    • project_limited: the maximum number of simultaneous connections from the user interface. Possible values: any integer number from 0 to MAX_INT32.
    • api_limited: the maximum number of simultaneous connections from the API. Possible values: any integer number from 0 to MAX_INT32. Used for bots only.
    • tracking: defines whether a customized logo is used. Possible values: 0 - a customized logo is used, 1 - no customized logo is used.
    • show_audience: defines whether to show Audience in the user interface. Possible values: 0 - don’t show Audience, 1 - show Audience.
    • autocomplete: defines whether to autocomplete key field names in filters. Possible values: 0 - don’t autocomplete, 1 - autocomplete.
  • has_microsoft_token: defines whether a Microsoft token exists. This token is used for exporting reports to OneDrive. Possible values: false - Microsoft token doesn't exist, true - Microsoft token exists.

list_calc_mappings method

•       Description:
  • Provides the list of calculated mappings. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/list_calc_mappings

• URL arguments:
• None
• POST arguments (required unless marked optional):
• project_name: the name of the project.
• token: the authorization token ( temporary or permanent ).
•   Output:
  • status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields only. Possible values:
    • success: the request was processed successfully.
  • • bad_request: invalid request parameters, please see the reason field for more details.
    • timeout: the request took too long to complete.
    • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
    • internal_error: the request failed due to an unknown problem.
  • reason: user-friendly description of the occurred error. This field is displayed for failed requests only.
  • result: an array of dictionaries with the following format:
    • name: mapping name (used in formulas as a link), unique across each project.
    • author: mapping author username.
    • created: mapping creation date.
    • updated: mapping update date.
    • mapped_key: mapped key name.
    • mappings: an array of dictionaries with the following structure:
      • key: mapping key.
      • value: mapping value.

query method

•    Description:
  • Returns report data restricted by query parameters passed in POST arguments. Returns report data restricted by query parameters passed in POST arguments. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/query   

• URL arguments:
• None
• POST arguments (required unless marked optional):
• slicer_name: the name of the report.
• project_name: the name of the project.
• token: the authorization token (temporary or permanent).
• limit (optional): the maximum number of returned rows. Possible values: any integer in the range from -1 to 100,000. -1 means all rows. The default value is 100. 
• offset (optional): skip the specified number of rows from the result. Together with the limit POST argument allows querying large datasets. The default value is 0. Can be used only, if the limit POST argument is in the range from 0 to 100,000.
• include_cumulative (optional): defines whether to display Total values for top N data rows, where N = limit + offset . Possible values: 0 - don't display Total values for top N data rows, 1 - display Total values for top N data rows. The default value is 0.
• split_by: an array of the key fields to split data by in the form of ["key_field1",...].
• include_mappings (optional): defines whether key field value mappings are returned by the API request. The default value is 1 (mappings are returned) if only 1 key field is used in the  split_by POST argument. The default value is 0 (mappings are not returned) if 2 or more key fields are used in the split_by POST argument.
• start_date: the start of the date range to gather data for. Supported formats:
  • Absolute dates: YYYY-MM-DD.
  • Relative dates:
    • today, yesterday
    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
    • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

    • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

      Template	Resulting start_date
      -15d_m_first	2021-09-01
      0d_m_first	2021-10-01
      15d_m_first	2021-10-01
      -100d_m_first	2021-07-01
      30d_m_first	2021-11-01

• • end_date: the end of the date range to gather data for. Supported formats:
    • Absolute dates: YYYY-MM-DD.
    • Relative dates:
      • today, yesterday
      • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.
      • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.
      • -Nm_first, -Nmonths_first, -Nm_last, and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

      • -Nd_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:

        Template	Resulting start_date
        -15d_m_first	2021-09-01
        0d_m_first	2021-10-01
        15d_m_first	2021-10-01
        -100d_m_first	2021-07-01
        30d_m_first	2021-11-01

  • timezone  (optional): time zone UTC offset in hours. Format: N, where N - any integer in the range of -12 <= N <= +12.
  • filters  (optional): an array with the following structure:
    • "name": "key_field",
    • "case_insensitive": (optional), defines whether search should be case-insensitive. Possible values: (1 - case-insensitive, 0 - case-sensitive). The default value is 0.
    • "search_mappings": (optional), defines whether the search should be performed in mappings. Possible values: (1 - search should be performed in both key field values and their mappings, 0 - search should be performed in key field values only). The default value is 0.
    • "value": ["value1", ... ],
    • "match": "equals|not equals|contains|not contains|beginswith|endswith|not beginswith|not endswith"

    where the value of the "value" field should be an array.

    If "search_mappings" is set to 1, the search will be performed for both specified key field values and their mappings (descriptions). For example, if you have the  creative_id  key field with some value of "1" and its mapping of "First Creative", you can search for it as follows:

    {"name": "creative_id", "value": ["First Creative"],"match":"equals", "search_mappings": 1} 
    
    OR 
    
    {"name": "creative_id", "value": [1],"match": "equals"} 

    Search results will be fully identical. 

    You can even use a partial matching, like {"name":"creative_id","value": ["Creative"],"match":" contains", "search_mappings": 1}, but please note that if you use a too short search string (1 - 2 characters long), it may take significant time to look up all matching records.

• • data_filters (optional): an array with the following structure:
    • "name": "data_field",
    • "value": "value1",
    • "match": "<|>|<=|>=”

    where the "value" field is just one value. The "match" can be "<" for less than value, ">" for greater than value, "<=" for less than or equal to value, or ">=" for greater than or equal to value. 

    If a data_field is in percent format, its value should also be divided by one hundred (30% becomes 0.3). Note, that this behavior is different in API and UI.

• • filter_template  (optional): a string template defining priorities for filters specified in the filters POST argument. Can contain the following elements:
    • opening/closing parentheses
    • OR/AND operators
    • "x" character as a placeholder for filters

    Example: "x OR (x AND x)".

    Filters from the filters POST argument in the specified order are substituted instead of x.

• data_filter_template  (optional): a string template defining priorities for filters specified in the data_filters POST argument. Can contain the following elements:
  • opening/closing parentheses
  • OR/AND operators
  • "x" character as a placeholder for filters

  Example: "x OR (x AND x)".

  Filters from the  data_filters  POST argument in the specified order are substituted instead of x.

• order_by  (optional): defines sorting rules. A single record or an array of records with the following structure:
  • "name": "field", the name of the key or data field to sort the results by. Note that this field can be any key field, specified in the split_by POST argument, or one of the data fields specified by the data_fields POST argument (or any of the data fields if the  data_fields POST argument is not specified). The default value is the first column with enabled percent.
  • "mapping": defines whether to sort by key field ID or by key field mapping. Possible values: (0 - sort by key field ID, 1 - sort by key field mapping). The default value is 0.
  • "direction": sort in the ascending or descending order, either ASC or DESC. The default value is DESC.

• • data_fields (optional):  the array of data fields to be returned in the form of [ "data_field1", .... ]. If it is not defined (by default), data fields will not be returned. To receive the details of all data fields available for your particular report use the info method.
  • include_others (optional): return the summary of data outside the specified limit.
    

• • data_filters (optional): an array with the following structure:
    • "name": "data_field",
    • "value": "value1",
    • "match": "<|>|<=|>=”

    where the "value" field is just one value. The "match" can be "<" for less than value, ">" for greater than value, "<=" for less than or equal to value, or ">=" for greater than or equal to value. 

    If a data_field is in percent format, its value should also be divided by one hundred (30% becomes 0.3). Note, that this behavior is different in API and UI.

• • data_filter_template (optional): a string template defining priorities for filters specified in the data_filters POST argument. Can contain the following elements:
    • opening/closing parentheses
    • OR/AND operators
    • "x" character as a placeholder for filters

    Example: "x OR (x AND x)".

    Filters from the  data_filters  POST argument in the specified order are substituted instead of x.

•    Description:
  • Converts slicer url to the JSON format list of POST arguments required for the corresponding API request. See example.
• URL:
• https://uslicer.iponweb.com/API/v2/url_to_api   

• URL arguments:
• None
• POST arguments (required unless marked optional):
• token: the authorization token (temporary or permanent).
• url: slicer url from the browser address bar.

   Output:

• slicer_name: the name of the slicer specified in the url POST argument.
• project_name: the name of the project specified in the url POST argument.
• limit: the maximum number of returned rows. The maximum allowed value is 10,000.
• split_by: the array of the key fields used to split data in the form of ["key_field1",...].
• include_mappings: defines whether key field value mappings were returned. Possible values: 1 (mappings were returned), 0 (mappings were not returned).
• start_date: the start_date value from the specified url POST argument. Format: YYYY-MM-DD.
• end_date: the end_date value from the specified url POST argument. Format: YYYY-MM-DD.
• include_others: defines whether the other N items link is displayed at the bottom of the data table for the slicer specified by the url  POST argument. Possible values: 1 (N items link is displayed), 0 (N items link is not displayed).
• filters (optional): the array of applied filters taken from the url POST argument. Array structure:
  
  • [ {"name": "key_field",
  • "case_insensitive": defines whether the search was case-insensitive. Possible values: (true - case-insensitive, false - case-sensitive).
  • "search_mappings": defines whether the search was performed in mappings. Possible values: (true - search was performed in both key field values and their mappings, false - search was performed in key field values only).
  • "value": ["value1", ... ],
  • "match":  "equals|not equals|contains|not contains"}, ... ] ,
• data_filters (optional): the array of applied data filters specified in the url POST argument. Array structure:
  •  [ {"name": "data_field",
  • "value": "value1",
  • "match": "<|>|<=|>=”}, ... ] ,

• data_fields (optional): the array of data fields specified in the url POST argument. Format: [ "data_field1", .... ].
• order_by: defines sorting rules specified in the url POST argument.
  • {"name" : "field", 
    
  • "direction" : DESC/ASC}

Back to Top