Reporting Query String Parameters

Here are the complete reference details for all query string parameters for the v3 Analytics Reporting API.

All parameter names are case-sensitive and lowercase.

The entire query string must be URL-encoded. Parameters limit and page need to be used in an API call to get the correct total count value.

General Syntax of Reporting GET

The base syntax of the route and query string is as follows. For ease of reading, the single-line request has been split across several lines.

[GET] /v3/analytics/reports/?
            report_type=type
            &dimensions=dimensions
            &metrics=metrics
            &filters=filter_type=='filter_value'
            &start_date=date
            &end_date=date
            &other_parms
            &api_key=your_api_key
         
  • The required query string parameters (shown in bold) are report_type, start_date, and api_key.
  • If no dimensions are specified, total values across all dimension are returned.
  • For time ranges up to 1 month you can query by up to 3 dimensions at a time with unlimited rows of data. For time ranges greater than one month you can query by up to 2 dimensions at a time with up to 10,000 rows of data.
  • If no metrics are specified, all metrics are returned.
Note: You may pass the API key either as a query parameter or via the header X-API-KEY.
Note: At this time, the only valid value for report_type is performance.
Note: You can only use 1 dimension (url) for url queries.

General Syntax of Reporting Long Queries POST

For queries with query parameters that would exceed the HTTP GET specification limit of 230 characters , please use a POST request. Some browsers and http clients may support more than 230 characters, but we will not provide official support for queries that violate the HTTP GET specification. For POST requests, pass a JSON object in the request body instead of the query string parameters.

[POST] /v3/analytics/reports

{
    "report_type":"type",
    "dimensions":"dimensions",
    "metrics":"metrics",
    "filters":"(filter_type==\"filter_value\")",
    "start_date":"date",
    "end_date":"date",
    "other_parms":"other_param_value",
    "api_key":"your_api_key"
}
         
Parameter Description Required

report_type

Specifies the type of report.

Valid values: performance

Default: None

Example: report_type=performance

Yes

start_date

The start date is specified as YYYY-MM-DD. To specify a start date with a start time you can specify YYYY-MM-DDTHH:MM. Time must be specified in values that are divisible by 15 minutes (for example, 02:00, 02:15, 02:30, 02:45, and so on). If you enter times that are not divisible by 15, an error message will be returned and your query will not be processed.

The value of start_date is the provider's timezone.

Default: None

Limitations: You can query a range of up to 1 year (366 days) for up to 2 filters and up to 1 month (31 days) for 3 filters. Queries using the hour and 15min time segments can only be made with a date rage of up to 7 days.

Example: start_date=2014-10-28

Yes

end_date

The end date is specified as YYYY-MM-DD.To specify a start date with a start time you can specify YYYY-MM-DDTHH:MM. Time must be specified in values that are divisible by 15 minutes (for example, 02:00, 02:15, 02:30, 02:45, and so on). If you enter times that are not divisible by 15, an error message will be returned and your query will not be processed.

Note: The end date is not inclusive. That is, data in the response is up to but not including the end date.

Default: Tomorrow's date in the provider's timezone.

Limitations: You can query a range of up to 1 year (366 days) for up to 2 filters and up to 1 month (31 days) for 3 filters. Queries using the hour and 15min time segments can only be made with a date rage of up to 7 days.

Example: To get data through the end of 2014-10-29: end_date=2014-10-29

No

metrics

List of comma-separated metric names.

Default: * (all metrics).

Valid values: See Metrics section for details.

Example: metrics=plays_requested,displays

No

dimensions

List of comma-separated dimension names. Results are grouped by the specified dimensions. If no dimensions are specified, total values across all dimension are returned.

Valid values: See Dimensions section for details.
  • For time ranges up to 1 month you can query by up to 3 dimensions at a time with unlimited rows of data.
  • For time ranges greater than one month you can query by up to 2 dimensions at a time with up to 10,000 rows of data.
    Note: You can only use 1 dimension for url queries.
  • Multiple values must be comma-separated with no spaces.
  • The order of multiple is not important:
    • dimensions=device_type,dma is the same as dimensions=dma,device_type

Default: None

Example: dimensions=country,region

No

filters

Restricts the set of results by specified filter values.
Note: For up to 2 filters you can set a date range of up to 1 year (366 days). For 3 filters you can set a date range of up to 1 month (31 days).

Valid values: See Filters for valid  filter names and boolean operations.

  • The value of filter_by must be URL-encoded.
  • The value of the actual filter must be enclosed in single quotation marks.

Default: None

Examples:
  • Filter by the country Australia: filters=country=='AU'
  • Filter by mobile devices in country Colombia filters=country==’CO’,device_type==’mobile’

No

time_segment

Specify the time-based segment for dimension data. See the discussion of behavior in About time_segment and Data Persistence. This will sort blocks of data.

Note: A week is defined as Monday - Sunday.

Valid values:   month | week | day| hour | 15min

Note: Queries using the hour and 15min time segments can only be made with a date rage of up to 7 days. Queries using the hour and 15min time segments will not return metric information for segment_watched, uniq_displays, uniq_video_starts, percentage_watched , uniq_plays_requested, or any Discovery metrics.

Default: None

Example: time_segment=day

No

sort

List of comma-separated metrics to sort by. For multiple metrics, sorts by the metrics in the order the metrics are placed in the query. You can explicitly use as many sort metrics as you want (given that you have the metric), but default sorting has a limit of two metrics.

Default: Sort by first two metrics (if present) in query order. Default value ordering is descending order. For ascending order, prefix a given metric with the + character.

Examples:
  • Plays requested, displays, and video starts in descending order: sort=plays_requested,displays,video_starts
  • Video starts in ascending order: sort=+video_starts
Note:

We recommend that you do not use segment_watched or percentage_watched for sorting. Please use other metrics, like plays_requested, instead.

There are different sort semantics for different metrics. For example, segment_watched and percentage_watched use the string (of the entire array) for sorting and do not use a numeric sort. This means that if you sort by segment_watched your results may not appear in numeric order. Your results may appear with the first result having a lower count of segment_watched than the second result (e.g. [99,…] , [999,...]).

In contrast, plays_requested uses a numeric sort, which will provide you with clear results.

No

limit

Limit the records returned in the response. Maximum limit: 1000. You can use the page parameter to paginate through all of your data. Note: Parameters limit and page need to be used in an API call to get the correct total count value.

Default: 1000

Example: limit=100

No

page

Integer for pagination. Starts with 0. Note: Parameters limit and page need to be used in an API call to get the correct total count value.

Default: 0

Example: For the second page: page=1

No

About time_segment and Data Persistence

The time range automatically expands to the minimal time range to fulfill the request. For example, specifying a start and end date for only today but with a time_segment of week causes the specified the start/end date to expand to cover the entire current week (in the provider's timezone). When there is no specified time_segment, the aggregate total for the specified dimensions is returned. When there is neither time_segment nor any specified dimension, the grand total for the time range is returned.

해당 내용이 도움 되었습니까?