Audience Endpoint

Returns audience data restricted by the query parameters passed in POST request body.

Request Fields

<!-- POST the request body to this endpoint -->
https://uslicer.iponweb.com/API/v2/audience

Audience Request Fields

Field	Description
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 of filters with the following details name (str) specifying the field you wish to query e.g. "name": "geo_country" value (array of str) specifying the values of the key fields e.g. "value": ["US", "CA"] match (str) Sets the conditions of how the names and values should be queried. It takes the following valid values: "equals" "not equals" "contains" "not contains" "begins with" "ends with" case_insensitive (int) (optional) 1 case-insensitive, 0 case-sensitive. The default value is 0. search_mappings (int) (optional) Defines whether the search should be performed using mappings. It takes the following valid values: 0 search should be performed using key field values only. The default value is 0. 1 search should be performed using both key field values and their mappings. If set to 1, 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.
split_by	An array of key field values from the filters field by which to split data. Takes the form of ["key_field1", "key_field2"].
start_date	Sets the start of the date range from which to gather data. 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 is any positive integer or zero. -Nm and -Nmonths for the number of months since the current date, where N is 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.
end_date	Sets the end of the date range from which to gather data. 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 is any positive integer or zero. -Nm and -Nmonths for the number of months since the current date, where N is 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.
timezone	(optional): Time zone UTC offset in hours, where N can be any integer in the range of -12 <= N <= +12

Response Fields

Audience Response Fields

Field	Description
status	Returns the status of the request, success if the request was processed successfully, or an error code if any error occurred. If the request is not successful, then the response contains the status and reason fields only. 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: this section contains 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 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. Note 2: If the split_by POST argument contains several key fields, queries returning more than 1,000,000 rows of data are rejected.
confidence_range	the confidence range for data (percent), presented in this section, if returned dataset is compressed. Available for every data row in the resulting dataset.

curl Example

curl --data '{"slicer_name":"","project_name":"","token":"<token>","split_by":"bid_context_wrapper.user.agent.browser.name","start_date":"2019-10-18","end_date":"2019-10-31","filters":[{"name":"bid_context_wrapper.user.geo.country","value":["US","CA"],"match":"equals"},{"name":"bid_context_wrapper.user.agent.browser.name","value":["Chrome"],"match":"contains"}]}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://uslicer.iponweb.com/API/v2/audience"

Request Example

{
    "slicer_name": "<name: ask Account Manager>",
    "project_name": "<name: ask Account Manager>",
    "token": "<token>",
    "split_by": [
        "bid_context_wrapper.user.agent.browser.name"
    ],
    "start_date": "2019-10-18",
    "end_date": "2019-10-31",
    "filters": [
        {
            "name": "bid_context_wrapper.user.geo.country",
            "value": [
                "US",
                "CA"
            ],
            "match": "equals"
        },
        {
            "name": "bid_context_wrapper.user.agent.browser.name",
            "value": [
                "Chrome"
            ],
            "match": "contains"
        }
    ]
}

Response Example

{
    "status": "success",
    "total": {
        "dates": [
            "2012-03-18",
            "2012-03-19",
            "2012-03-20"
        ],
        "data": [
            {
                "value": 664019,
                "name": "unique_users"
            }
        ],
        "records_found": 5,
        "confidence_range": "0.00245"
    },
    "rows": [
        {
            "name": [
                "MSIE6"
            ],
            "data": [
                {
                    "value": 6210,
                    "name": "unique_users"
                }
            ],
            "confidence_range": "0.02538"
        },
        {
            "name": [
                "MSIE9"
            ],
            "data": [
                {
                    "value": 272940,
                    "name": "unique_users"
                }
            ],
            "confidence_range": "0.00383"
        },
        {
            "name": [
                "MSIEOther"
            ],
            "data": [
                {
                    "value": 27,
                    "name": "unique_users"
                }
            ],
            "confidence_range": "0.37771"
        },
        {
            "name": [
                "MSIE7"
            ],
            "data": [
                {
                    "value": 176570,
                    "name": "unique_users"
                }
            ],
            "confidence_range": "0.00476"
        },
        {
            "name": [
                "MSIE8"
            ],
            "data": [
                {
                    "value": 208284,
                    "name": "unique_users"
                }
            ],
            "confidence_range": "0.00438"
        }
    ]
}