Skip to content

time_series

Specification

  • Description:

  • Returns time series data restricted by query parameters passed in POST arguments. See example.

  • URL:

  • https://uslicer.iponweb.com/API/v2/time_series

  • URL arguments:

  • None

  • POST arguments (required unless marked optional):

  • slicer_name: the name of the report to slice data for.

  • project_name: the name of the project.
  • token: the authorization token (see Authentication).
  • granularity: X-axis category.
  • limit: (optional) the maximum number of returned rows. The maximum number is 10,000, the default number is 30. Used only, if granularity is not a time-related key field.
  • order_by\(optional): defines sorting rules:
  • {" name": "field",

  • "direction": DESC/ASC}, where:

    • name: the name of the key or data field to sort the results by. Note that this field can be granularity, any key field, specified in the split_by POST argument, or any data field. The default value is granularity.
    • direction: sort in the ascending or descending order, either ASC or DESC. The default direction is ASC.

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

  • chart_lines: an array of key field values for which Chart plots are required. Can contain the special value of "__total__" to draw the Total plot. These key fields should be specified in the split_by POST argument. If the split_by POST argument contains several key fields, the values of these key fields should be separated by the START OF TEXT character with code 2, which has different representations in different systems, like ‘\x02’ or '\u0002'. The maximum number of chart lines is 50.

  • data_field: the requested data field.

  • start_date: the start of the date range to gather data for. Supported formats:

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

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

  • 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: this section contains optional mappings for requested chart lines.
    • rows: this section contains query data results. It is an array of data rows, each containing the following fields:
    • **__mapping__ **: granularity mapping.
    • requested chart_lines: data for all requested chart lines in the following format:
      • "chart line value": data_field value
    • __time__: granularity value for this row in the following format:
      • granularity : granularity _ hour:
      • "time": "2015-09-30 19:00”
      • granularity: granularity _ day
      • "time": "2015-09-30"
      • granularity: granularity _ week
      • "time": "2015-W26"
      • granularity: granularity _ month
      • "time": "2015-09"
      • granularity: granularity _ quarter
      • "time": "2015 Q2"
      • granularity: granularity _ year
      • "time": "2015"
      • granularity: key field value
      • "time": "Managed"
    • __markers__ (optional): an array of dictionaries with the following fields:
      • edited: marker last edition time with selected granularity.
      • created: marker creation time with selected granularity.
      • first_name: the first name of the marker author.
      • last_name: the last name of the marker author.
      • author: the login of the marker author.
      • date_ts: the timestamp of the marker on the chart in seconds since January 01, 1970.
      • referer: u-Slicer URL matching the specified POST arguments.
      • granularity: selected chart granularity.
      • date: the date of the marker on the chart with selected granularity and time zone.
      • message: the message posted by the marker author.
      • marker_id: unique marker ID, an integer number assigned by the system automatically.

Example

Purpose: Get Plots of Impressions related to Campaign 9861, occurred for users of Chrome and Firefox in California and Texas during the period from March 01, 2012 to March 03, 2012.

Path:

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

POST Arguments:

{
   "slicer_name": "Traffic Demo",
   "project_name": "demo",
   "token": "<token>",
   "split_by" : [
      "campaign_id","geo_region"
      ],
   "start_date" : "2012-03-01",
   "end_date" : "2012-03-03",
   "granularity" : "day",
   "data_field" : "imps",
   "chart_lines" : [
      "9861\u0002US-TX", "9861\u0002US-CA",
      ],
   "filters" : [
      {
         "name" : "geo_region",
         "value" : [
            "California", "Texas"
         ],
         "match" : "equals"
      },
      {
         "name" : "campaign_id",
         "values" : [
            "100"
         ],
         "match" : "contains"
      },
      {
         "name" : "browser",
         "value" : [
            "Opera"
         ],
         "match" : "equals"
      }
   ]
}

Command:

curl --data '{"slicer_name": "Traffic Demo", "project_name": "demo", "token": "<token>", "data_field": "imps", "granularity": "day","split_by": ["campaign_id","geo_region"],"start_date": "2012-03-01","end_date": "2012-03-03", "chart_lines": ["9861\u0002US-TX", "9861\u0002US-CA"], "filters": [{"name": "geo_region", "value" :["California", "Texas"],"match": "equals"}, {"name": "campaign_id","value" :["100"],"match": "contains"}, {"key": "browser", "value" :["Opera"], "match": "equals"}]}' -H "Content-Type: application/json" -H "Accept: application/json" "https://uslicer.iponweb.com/API/v2/time_series"

Response:

{
   "mappings" : {
      "geo_region" : {
         "US-CA" : "California",
         "US-TX" : "Texas"
      },
      "campaign_id" : {
         "9861" : null
      }
   },
   "status" : "success",
   "rows" : [
      {
         "9861\u0002US-CA" : 41677,
         "__time__" : "2012-03-01",
         "9861\u0002US-TX" : 14064
      },
      {
         "9861\u0002US-CA" : 27740,
         "__time__" : "2012-03-02",
         "9861\u0002US-TX" : 20234
      },
      {
         "9861\u0002US-CA" : 18672,
         "__time__" : "2012-03-03",
         "9861\u0002US-TX" : 20305
      }
   ]
}