Skip to content

audience

POST /API/v2/audience

Returns audience data. See example.

Request body

  • slicer_name: the name of the report.
  • project_name: the name of the project.
  • 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:

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

    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

  • 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",
  "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",
  "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" \
-H "Authorization: Bearer <token>" \
"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"
    }
  ]
}