Skip to content

query

POST /API/v2/query
Returns report data restricted by query parameters passed in POST arguments. See example.

Request body

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

  • filters(optional): an array with the following structure:

  • data_filters(optional): an array with the following structure:

  • filter_template (optional): a string template defining priorities for filters specified in the filters POST argument. Can contain the following elements:

  • data_filter_template (optional):a string template defining priorities for filtersspecified in the data_filters POST argument. Can contain the following elements:

  • order_by  (optional): defines sorting rules. A single record or an array of records with the following structure:

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

  • data_field_options (optional): An array of objects used to specify additional query parameters for individual data fields. Each object supports the following structure:

  • include_others (optional): return the summary of data outside the specified limit.

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.
      • comment (optional): calculation comment (only for custom data columns), can be inf, -inf in case of stack overflow, "Division by zero", and ERROR! at any other errors in calculation. In all of these cases, the value is displayed as 0.
    • records_found: the total number of found records.
    • confidence_range: the confidence range for data (in percent) in this section, if the returned dataset is compressed. Available for the Total rows. Contains “N/A” if compressed is unknown and 0 for uncompressed rows.
    • dates: the array with all the dates, for which data exist in the period from the start_date to the end_date.
  • cumulative (optional): this section contains Total values for top N data rows, where N = limit + offset, if the include_cumulative POST argument was set to 1.
    • data: the list of Total values matching top N data rows for the data fields specified in the data_fields POST argument. It's an array of elements with the following fields:
    • name: data field name.
    • value: data field Total value for top N data rows.
    • percent (optional): percent of the data field Total value for top N data rows (if applicable).
    • confidence_range: the confidence range for data (in percent) in this section, if the returned dataset is compressed. Available for the Total values matching top N data rows. Contains “N/A” if compressed is unknown and 0 for uncompressed rows.
    • key_count: the number of top N data rows, where N = limit + offset if the include_cumulative POST argument was set to 1.

  • 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 the following field names and values:

    • name:data field name.

    • value: data field value.
    • percent (optional): percent of the total value (if applicable).
    • comment(optional): calculation comment (only for custom data columns), can be inf, -inf in case of stack overflow, Division by zero", and ERROR! at any other errors in calculation. In all of these cases, the value is displayed as 0.
    • 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.

  • mapping (optional): the mappings of the current row key field values for the key fields specified in the split_by POST argument. Mapping display is defined by the include_mappings POST argument.

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

  • percent (optional): percent of the data field Total value for data rows beyond the range defined by limit + offset (if applicable).

  • confidence_range: the confidence range for data (in percent) in this section, if the returned dataset is compressed. Available for the Total values matching data rows beyond the range defined by limit + offset. Contains “N/A” if compressed is unknown and 0 for uncompressed rows.

  • key_count: the number of data rows beyond the range defined by limit + offset.

  • others(optional): the summary of data rows beyond the range defined by limit + offset, if the include_others POST argument was set to 1. It's an array of elements with the following fields:

  • data: the list of Total values of data rows beyond the range defined by limit + offset for the data fields specified in the data_fields POST argument. It's an array of elements with the following fields:
    • name: data field name.
    • value: data field Total value for data rows beyond the range defined by limit + offset.

Example

Generate a Report on all Campaigns, containing the "100" string, displayed in California and Texas to users of the Opera internet browser for the period from March 01, 2012 to March 03, 2012, and show the following data fields only:

  • imps
  • clicks
  • pub_payout
  • ecpm

Path:

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

Request

{
  "slicer_name": "Traffic Demo",
  "project_name": "demo",
  "token": "<token>",
  "split_by" : "campaign_id",
  "start_date" : "2012-03-01",
  "end_date" : "2012-03-03",
  "filters" : [
    {
      "name" : "geo_region",
      "value" : [
        "California",
        "Texas"
      ],
      "match" : "equals",
      "search_mappings": 1
      },
      {
        "name" : "campaign_id",
        "values" : [
          "100"
        ],
        "match" : "contains"
      },
      {
        "name" : "browser",
        "value" : [
          "Opera"
        ],
        "match" : "equals"
      }
  ],
  "data_fields" : [
    "imps",
    "clicks",
    "pub_payout",
    "ecpm"
  ]
}

curl --data '{
  "slicer_name": "Traffic Demo",
  "project_name": "demo",
  "token": "<token>",
  "split_by": "campaign_id",
  "start_date": "2012-03-01",
  "end_date": "2012-03-03",
  "filters": [
    {
      "name": "geo_region",
      "value" :[
        "California",
        "Texas"
      ], 
      "match": "equals", 
      "search_mappings": 1
    },
    {
      "name": "campaign_id",
      "value" :[
        "100"
      ],
      "match": "contains"
    },
    {
      "name": "browser",
      "value" :[
        "Opera"
      ],
      "match": "equals"
    }
  ], 
  "data_fields" :[
    "imps",
    "clicks",
    "pub_payout",
    "ecpm"
  ]
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token>" \
  "https://uslicer.iponweb.com/API/v2/query"

Response

{
  "status" : "success",
  "rows" : [
    {
      "mapping" : null,
      "name" : "10065",
      "data" : [
        {
          "value" : 1018,
          "percent" : "50.88339",
          "name" : "imps"
        },
        {
          "value" : 1,
          "percent" : "100.00000",
          "name" : "clicks"
        },
        {
          "value" : 0.29,
          "percent" : "30.36148",
          "name" : "pub_payout"
        },
        {
          "value" : 0.29,
          "percent" : null,
          "name" : "ecpm"
        }
      ],
      "confidence_range" : "N/A"
    },
    {
      "mapping" : null,
      "name" : "10072",
      "data" : [
        {
          "value" : 951,
          "percent" : "47.52650",
          "name" : "imps"
        },
        {
          "value" : 0,
          "percent" : "0.00000",
          "name" : "clicks"
        },
        {
          "value" : 0.57,
          "percent" : "59.11783",
          "name" : "pub_payout"
        },
        {
          "value" : 0.604,
          "percent" : null,
          "name" : "ecpm"
        }
      ],
      "confidence_range" : "N/A"
    },
    {
      "mapping" : null,
      "name" : "10056",
      "data" : [
        {
          "value" : 32,
          "percent" : "1.59011",
          "name" : "imps"
        },
        {
          "value" : 0,
          "percent" : "0.00000",
          "name" : "clicks"
        },
        {
          "value" : 0.1,
          "percent" : "10.52068",
          "name" : "pub_payout"
        },
        {
          "value" : 3.211,
          "percent" : null,
          "name" : "ecpm"
        }
      ],
      "confidence_range" : "N/A"
    }
  ],
  "total" : {
    "dates" : [
      "2012-03-01",
      "2012-03-02",
      "2012-03-03"
    ],
    "data" : [
      {
        "value" : 2000,
        "name" : "imps"
      },
      {
          "value" : 1,
          "name" : "clicks"
      },
      {
          "value" : 0.97,
          "name" : "pub_payout"
      },
      {
          "value" : 0.485,
          "name" : "ecpm"
      }
    ],
    "records_found" : 3,
    "confidence_range" : "N/A"
  }
}

If no data exists for the specified combination of keys, values and match types, the response is as follows:

Response

{
  "status" : "success",
  "rows" : [],
  "total" : {
      "dates" : [
        "2012-03-01",
        "2012-03-02",
        "2012-03-03"
      ],
      "data" : [
        {
            "value" : 0,
            "name" : "imps"
        },
        {
            "value" : 0,
            "name" : "clicks"
        },
        {
            "value" : 0,
            "name" : "pub_payout"
        },
        {
            "value" : 0,
            "name" : "ecpm"
        }
      ],
      "records_found" : 0,
      "confidence_range" : "N/A"
  }
}

If you specify a wrong slicer name, the following error message is displayed:

Response

{
  "status" : "access_error",
  "reason" : "Wrong slicer name or slicer is unavailable"
}