Skip to content

audience

POST /API/v2/audience

Return audience data.

Request body

  • slicer_name: the name of the report.

  • project_name: the name of the project.

  • token: the authorization token (see Authentication).

  • split_by: an array of the key fields to split data by in the form of ["key_field1",...].

  • start_date, end_date: the start/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.

  • 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".

    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 a value of "1" and its mapping of "First Creative", you can search for it as follows:

    Example

    {
  "name": "creative_id",
  "value": [1],
  "match": "equals"
}

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

    {
  "name": "creative_id",
  "value": ["Creative"],
  "match": "contains",
  "search_mappings": 1
}

    Search results for the first two examples will be fully identical. However, if you use partial matching (as in the third example), note that short search strings (1–2 characters long) may significantly increase the time required to look up all matching records.

Response

  • 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.

Example

For US and Canada generate a Report on the estimated number (with confidence range) of unique users for each browser containing the "MS" string in its name.

Path:

https://uslicer.iponweb.com/API/v2/audience

Request

{
  "slicer_name": "Traffic Demo",
  "project_name": "demo",
  "token": "<token>",
  "split_by": "browser",
  "start_date": "2012-03-18",
  "end_date": "2012-03-20",
  "filters": [
    {
      "name" : "geo_country",
      "value" : ["US", "CA"],
      "match" : "equals"
    },
    {
      "name" : "browser",
      "value" : ["MS"],
      "match" : "contains"
    }
  ]
}

curl --data '{
  "slicer_name": "Traffic Demo",
  "project_name": "demo",
  "token": "<token>",
  "split_by": "browser",
  "start_date": "2012-03-18",
  "end_date": "2012-03-20",
  "filters": [
    {
      "name": "geo_country",
      "value": ["US", "CA"],
      "match": "equals"
    },
    {
      "name": "browser",
      "value": ["MS"],
      "match": "contains"
    }
  ]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
"https://uslicer.iponweb.com/API/v2/audience"

Response

{
  "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"
    }
  ]
}