Data Extraction API Parameters

Parameters used in Data Extraction API requests.

account name | top

Use the account_name parameter to specify a sub-account in which to query profiles. To use this parameter, you must be authenticated to the parent account, and have access rights to the sub-account.

account_name = name of the account
Example: specifying the account name

account_name=mySubAccount

callback | top

Use the callback parameter to create a JSONP request. When format=json, the API checks for &callback=function. In the example, the JSONP request retrieves a list of time periods.

Example request:
<html>
<head>
<title>JSONP Example</title>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script type="text/javascript">
               function parseResult(data)
               {
                               $.each(data, function (index, value) {
                $("#p").append('<li>' + index + ': ' + value + '</li>');
            });
               }
</script>
</head>
<body >
                <ul id="p">
</ul>
<script type="text/javascript" src="https://ws.webtrends.com/v3/Reporting/profiles/400/reports/95df19b6d9e/periods/?callback=parseResult"></script>
</body>
</html>
Example response:
  • DayStart: 2007m08d17
  • DayEnd: 2011m08d08
  • WeekStart: 2007w33
  • WeekEnd: 2011w33
  • MonthStart: 2007m08
  • MonthEnd: 2011m08
  • QuarterStart: 2007q03
  • QuarterEnd: 2011q03
  • YearStart: 2007y2007
  • YearEnd: 2011y2011

end period | top

Use the end_period parameter specify the ending day of a date range. You must also supply the beginning day. end_period is an optional parameter. If end_period is not supplied, the data returned will only be from the time specified by start_period. Supplying only start_period is the same as supplying start_period and end_period with the same value.

Example: specifying January 1, 2009 to January 30, 2009

start_period=2009m01d01&end_period=2009m01d30

Example: specifying the past 7 days (from yesterday)

start_period=current_day-7&end_period=current_day-1

Example: specifying hourly data for March 21, 2009

start_period=2009m03d20h00&end_period=2009m03d21h23

Example: specifying hourly data for yesterday
start_period=current_day-1
Note: Several time period macros are available: CURRENT_HOUR, CURRENT_DAY, CURRENT_DAY_MIDNIGHT, CURRENT_MONTH and CURRENT_YEAR. Instead of a specific start and end date, you can identify relative time periods.

For example, to get data for last month, specify start_period=current_month-1.

To get hourly real-time data from midnight of the current day, up to the current hour, use CURRENT_DAY_MIDNIGHT. For example:
https://ws.webtrends.com/v3/Reporting/profiles/20476/Keymetrics/
?start_period=current_day_midnight&end_period=current_hour
&language=en-US&suppress_error_codes=true&format=html&period_type=trend
end_period = ending day of date range

format | top

format = return data format
Data format Parameter and value
JSON format=json

This is the default format; JSON is returned if you do not supply a format parameter.

XML format=xml
XML2 ("XPath-friendly" XML for dynamic applications) format=xml2
HTML format=html (use this when importing data into Excel)
CSV format=csv
Note: Report data in XML, XML2 and JSON formats now represents calendar dates in ISO 8601 format: YYYY-MM-DD. The JSON data structure for dates is also different in version 3. In prior versions, the calendar date October 10, 2011 was represented like this:
… data": {
	"10/10/2011": {…

In version 3, the JSON format for calendar dates is:

… data": [
	{
	"period": "Day",
	"start_date": "2011-10-10",
	"end_date": "2011-10-10",

language | top

Use the language parameter with a language ID, such as en or locale ID, such as en-GB to specify language and locale preferences for translating and formatting dates and numbers in report data. (See ISO 639-1 and ISO-3166 for codes.)

The languages available are those that appear in the Analytics user interface as preferences:

Language preference being selected in the Analytics user interface.
Note: Strictly speaking, language=en_GB is a locale identifier for English-language speakers in Great Britain. (A hyphen is used to designate a dialect of a language, so the dialect for a resident of Great Britain is en-GB). In practice, however, due to the widespread lack of understanding of this distinction, "-" and "_" are treated as equivalent.
language = language code[-dialect designator]

measures | top

Use the measures parameter to specify the measures to return. If you do not use this parameter, or if you specify a measure ID for which there is no measure, all measures are returned.

Example: returning only visits and visitors

measures=1*2

measures = measureID1 * measureID2 * ...

period_type | top

Use the period_type parameter to specify how you'd like report data returned.

indv
Return every period in the period range individually (use this for multi-dimensional reports). Example:
https://ws.webtrends.com/v3/Reporting/profiles/15685/reports/95df19b6d9e/?format=html&suppress_error_codes=true&period_type=indv
trend
Return the result trended (only for the first dimension). Example:
https://ws.webtrends.com/v3/Reporting/profiles/15685/reports/95df19b6d9e/?format=html&suppress_error_codes=true&period_type=trend
agg
Aggregate all values. Example:
https://ws.webtrends.com/v3/Reporting/profiles/15685/reports/95df19b6d9e/?format=html&suppress_error_codes=true&period_type=agg
period_type = indv | trend | agg

query | top

Use the query parameter to filter returned data. These rules apply to using the query parameter:

Example: return all rows where State is like Carolina
https://ws.webtrends.com/v3/Reporting/profiles/ProfileId/reports/nxKfV54n7l5/?query=State%20like%20'*Carolina'&start_period=current_month-1&end_period=current_month&format=html&end_period=current_month&period_type=agg&format=html
Example: return all rows where State is like Carolina and City is not Charlotte
https://ws.webtrends.com/v3/Reporting/profiles/ProfileId/reports/nxKfV54n7l5/?query=State%20LIKE%20'*Carolina'%20AND%20City%20NEQ%20'Charlotte'&start_period=current_month-1&end_period=current_month&format=html
Example: return all rows where City is Charlotte
https://ws.webtrends.com/v3/Reporting/profiles/ProfileId/reports/nxKfV54n7l5/?query=City%20=%20'Charlotte'&start_period=current_month-1&end_period=current_month&format=html
Example: return all rows where City is Charlotte or Raleigh
https://ws.webtrends.com/v3/Reporting/profiles/ProfileId/reports/nxKfV54n7l5/?query=City%20=%20'Charlotte'%20OR%20City%20=%20'Raleigh'&start_period=current_month-1&end_period=current_month&format=html
query ::= < statement >

range | top

Use the range parameter to specify the start and end rows of the range of rows to return. If you specify only end row, start row defaults to 1. If you do not use this parameter, all rows are returned.

Note: The range parameter cannot be used in drill-down reports, since they contain a hierarchy of ranges.
Example: specifying ranges
Range Parameter and value
First 100 rows range=100
Rows 101 to 200 range=101*200
range = start row * end row

sortby | top

Use the sortby parameter to sort report data by a measure. If you don't provide a measure, the report is sorted by the first measure.

Note: Use the get report definition method to get the list of measures available for a report definition. Valid values for the sortby parameter are measure names, for example (in XML format), Downloads:
<string name="name">Downloads</string>
If measure names contain spaces, replace them with %20 to create the sortby parameter value, for example: sortby=bounce%20rate.
Default sort is by the first measure, Visits (sortby not used):
https://ws.webtrends.com/v3/Reporting/profiles/ProfileId/reports/JHWXJNcP0P6/?start_period=current_month-1&end_period=current_month&format=html

If the sortby parameter is not used, reports sort by the first measure.

Sort by Bounce Rate:
https://ws.webtrends.com/v3/Reporting/profiles/ProfileId/reports/JHWXJNcP0P6/?start_period=current_month-1&end_period=current_month&format=html&sortby=bounce%20rate&totals=none

Report sorted by bounce rate.

sortby = URL-encoded measure name

start_period | top

Use the start_period parameter to specify the beginning day of a date range. end_period is an optional parameter. If end_period is not supplied, the data returned will only be from the time specified by start_period. Supplying only start_period is the same as supplying start_period and end_period with the same value.

Example: specifying January 1, 2009 to January 30, 2009
start_period=2009m01d01&end_period=2009m01d30
Example: specifying the past 7 days (from yesterday)
start_period=current_day-7&end_period=current_day-1
Note: Several time period macros are available: CURRENT_HOUR, CURRENT_DAY, CURRENT_DAY_MIDNIGHT, CURRENT_MONTH and CURRENT_YEAR. Instead of a specific start and end date, you can identify relative time periods.

For example, to get data for last month, specify start_period=current_month-1.

To get hourly real-time data from midnight of the current day, up to the current hour, use CURRENT_DAY_MIDNIGHT. For example:
https://ws.webtrends.com/v3/Reporting/profiles/20476/Keymetrics/
?start_period=current_day_midnight&end_period=current_hour
&language=en-US&suppress_error_codes=true&format=html&period_type=trend
Example: specifying hourly data for March 21, 2009

start_period=2009m03d20h00&end_period=2009m03d21h23

Example: specifying hourly data for yesterday
start_period=current_day-1
Note: Several time period macros are available: CURRENT_HOUR, CURRENT_DAY, CURRENT_DAY_MIDNIGHT, CURRENT_MONTH and CURRENT_YEAR. Instead of a specific start and end date, you can identify relative time periods.

For example, to get data for last month, specify start_period=current_month-1.

To get hourly real-time data from midnight of the current day, up to the current hour, use CURRENT_DAY_MIDNIGHT. For example:
https://ws.webtrends.com/v3/Reporting/profiles/20476/Keymetrics/
?start_period=current_day_midnight&end_period=current_hour
&language=en-US&suppress_error_codes=true&format=html&period_type=trend
start_period = first day of date range

suppress_error_codes | top

Set the suppress_error_codes parameter to true if you do not want to be notified of error conditions for a request (the default is false).

Example: Suppress errors for a request

suppress_error_codes=true

Note: For Excel imports, set the suppress_error_codes parameter to true. Otherwise, requests that return any HTTP status code other than 200 (success) cause Excel to disable the connections for such requests. Setting suppress_error_codes=true ensures that all errors return a 200 status code to Excel, but the message text associated with the error still appears.
suppress_error_codes = {true|false}

totals | top

The totals parameter specifies whether, or how, totals for measures are returned: all (default), only or none.

Note:

If you use the range parameter to return a subset of data, the totals returned are the subtotals for the entire period, rollup dimension, etc. as shown below.

For subsets of data, specify totals=none and use Excel to compute the totals.

What to return Parameter and value
No totals totals=none
All totals (the default) totals=all
Only totals totals=only
totals = {all | only | none}