time_series

POST /API/v2/time_series

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

Request body¶

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", the name of the key or data field to sort the results by. Note that this field can be any key field, specified in the split_by POST argument, or one of the data fields specified by the data_fields POST argument (or any of the data fields if the data_fields POST argument is not specified). The default value is the first column with enabled percent.
- "mapping": defines whether to sort by key field ID or by key field mapping. Possible values: (0 - sort by key field ID, 1 - sort by key field mapping). The default value is 0.
- "direction": sort in the ascending or descending order, either ASC or DESC. The default value is DESC.
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, end_date: the start/end of the date range to gather data for. Supported formats:
- Absolute dates: YYYY-MM-DD.
- Relative dates:
  - today, yesterday
  - - N d and - N days for the number of days since the current date, where N - any positive integer or zero.
  - - N m and - N months for the number of months since the current date, where N - any positive integer or zero.
  - - N m_first, - N months_first, - N m_last, and - N months_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.
  - -N d_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.
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"
where 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 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.
data_filters(optional): an array with the following structure:
- "name": "data_field",
- "value": "value1",
- "match": "<|>|<=|>=”
where the "value" field is just one value. The "match" can be "<" for less than value, ">" for greater than value, "<=" for less than or equal to value, or ">=" for greater than or equal to value.

If a data_field is in percent format, its value should also be divided by one hundred (30% becomes 0.3). Note, that this behavior is different in API and UI.
data_filter_template(optional): a string template defining priorities for filters specified in the data_filters POST argument. Can contain the following elements:
- opening/closing parentheses
- OR/AND operators
- "x" character as a placeholder for filters
Example: "x OR (x AND x)".

Filters from the data_filters POST argument in the specified order are substituted instead of x.

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

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

Path:

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

Request

JSONcurl

{
  "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" : [
          "9861"
        ],
        "match" : "equals"
      },
      {
        "name" : "browser",
        "value" : [
          "Opera"
        ],
        "match" : "equals"
      }
  ]
}

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

JSON

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

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