Time Series Endpoint

Returns a time series of data restricted by the query parameters passed in the POST

<!-- POST the request body to this endpoint -->
https://uslicer.iponweb.com/API/v2/time_series

Request Fields

Time Series Request Fields

Field

Description

granularity

A string, specifying the time granularity to use. Takes the following values, hour, day, week, month, quarter, or year

limit

(optional) The maximum number of returned rows. Possible values: any integer in the range from 1 to 10,000. The default value is 30.

split_by

An array of key values from those set in the filters field by which to split data. Takes the form of ["key_field1", "key_field2"].

start_date

Sets the start of the date range from which to gather data. 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 is any positive integer or zero.

    • -Nm and -Nmonths for the number of months since the current date, where N is 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.

end_date

Sets the end of the date range from which to gather data. 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 is any positive integer or zero.

    • -Nm and -Nmonths for the number of months since the current date, where N is 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.

timezone

(optional): Time zone UTC offset in hours, where N can be any integer in the range of -12 <= N <= +12

filters

(optional) An array of filters, each filter is built using the following format:

  • name (str) Specifies the key you wish to query e.g. "name": "bid_context_wrapper.user.geo.country"

  • value (array of str) Specifies the values for the key you want to query e.g. "value": ["US", "CA"]

  • search_mappings (optional), defines whether the search should be performed in mappings. Possible values:

    • 0 search should be performed in key field values only, this is tge default.

    • 1 search should be performed in both key field values and their mappings,

    • 2 - search should be performed in key field mappings only). The default value is 0.

  • match (str) Sets the conditions of how the names and values should be queried. It takes the following valid values:

    • "equals"

    • "not equals"

    • "contains"

    • "not contains"

    • "begins with"

    • "ends with"

  • case_insensitive (int) (optional)

    • 0 case-sensitive. The default value is 0.

    • 1 case-insensitive

chart_lines

(Required) 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

[ "\u0002bid_context_wrapper.demand.campaign_id", "\u0002bid_context_wrapper.supply.site_domain", "__total__" ]

Response Fields

Time Series Request Fields

Field

Description

status

Returns the status of the request, success if the request was processed successfully, or an error code if any error occurred. If the request is not successful, then the response contains the status and reason fields only.

  • 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

Returns the status of the request, success if the request was processed

mappings

This section contains optional mappings for requested chart lines.

rows

An array of objects, defining the data returned using the filters and chart_lines specified in the POST request.

Request Example

{
    "slicer_name":"",
    "project_name":"",
    "timezone":1,
    "token":"token",
    "split_by":[
        "bid_context_wrapper.demand.campaign_id",
        "bid_context_wrapper.supply.site_domain"
    ],
    "start_date":"2019-10-15",
    "end_date":"2019-10-28",
    "granularity":"day",
    "chart_lines":[
        "\u0002bid_context_wrapper.demand.campaign_id",
        "\u0002bid_context_wrapper.supply.site_domain",
        "__total__"
    ],
    "filters":[
        {
            "name":"bid_context_wrapper.demand.campaign_id",
            "value":[
                "3"
            ],
            "match":"contains",
            "case_insensitive":1
        },
        {
            "name":"bid_context_wrapper.supply.site_domain",
            "value":[
                "thesauraus.com"
            ],
            "match":"contains",
            "case_insensitive":1
        }
    ],
    "data_field":"imps"
}

Response Example

{
    "mappings": {
        "bid_context_wrapper.demand.campaign_id": {},
        "bid_context_wrapper.supply.site_domain": {
            "bid_context_wrapper.demand.campaign_id": null,
            "bid_context_wrapper.supply.site_domain": null
        }
    },
    "rows": [
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-15",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-16",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-17",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-18",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-19",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-20",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-21",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-22",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-23",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-24",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-25",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-26",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-27",
            "__total__": 0
        },
        {
            "\u0002bid_context_wrapper.demand.campaign_id": 0,
            "\u0002bid_context_wrapper.supply.site_domain": 0,
            "__time__": "2019-10-28",
            "__total__": 0
        }
    ],
    "status": "success"
}