Required Parameters
|
endDate
|
string
The end date for fetching
YouTube Analytics
data. The value should be in
YYYY-MM-DD
format.
The API response contains data up until the last day for which all metrics
in the query
are available at the time of the query. So, for example, if the request specifies an end date of July 5, 2017, and values for all of the requested metrics are only available through July 3, 2017, that will be the last date for which data is included in the response. (That is true even if data for some of the requested metrics is available for July 4, 2017.)
Note:
In version 1 of the API, this parameter was named
end-date
.
|
ids
|
string
Identifies the YouTube channel or content owner for which you are retrieving
YouTube Analytics
data.
- To request data for a YouTube channel, set the
ids
parameter value to either
channel==MINE
or
channel==
CHANNEL_ID
, where
CHANNEL_ID
identifies the currently authenticated user's YouTube channel.
- To request data for a YouTube content owner, set the
ids
parameter value to
contentOwner==
OWNER_NAME
, where
OWNER_NAME
is the
content owner ID
for the user.
|
metrics
|
string
A comma-separated list of
YouTube Analytics
metrics, such as
views
or
likes,dislikes
. See the documentation for
channel reports
or
content owner reports
for a list of the reports that you can retrieve and the metrics available in each report. (The
Metrics
document contains definitions for all of the metrics.)
|
startDate
|
string
The start date for fetching
YouTube Analytics
data. The value should be in
YYYY-MM-DD
format.
Note:
In version 1 of the API, this parameter was named
start-date
.
|
Optional Parameters
|
currency
|
string
The currency that the API will use to specify the following estimated revenue metrics:
estimatedRevenue
,
estimatedAdRevenue
,
estimatedRedPartnerRevenue
,
grossRevenue
,
cpm
,
playbackBasedCpm
. The values that the API returns for those metrics are estimates calculated using exchange rates that change on a daily basis. If none of those metrics are requested, the parameter is ignored.
The parameter value is a three-letter ISO 4217 currency code from the list of currencies below. The API returns an error if an unsupported currency is specified. The default value is
USD
.
See supported currencies
Currency codes
|
AED
|
United Arab Emirates dirham
|
ANG
|
Netherlands Antillean guilder
|
ARS
|
Argentine peso
|
AUD
|
Australian dollar
|
BDT
|
Bangladeshi taka
|
BGN
|
Bulgarian lev
|
BHD
|
Bahraini dinar
|
BND
|
Brunei dollar
|
BOB
|
Boliviano
|
BRL
|
Brazilian real
|
BWP
|
Botswana pula
|
CAD
|
Canadian dollar
|
CHF
|
Swiss franc
|
CLP
|
Chilean peso
|
CNY
|
Chinese yuan
|
COP
|
Colombian peso
|
CRC
|
Costa Rican colon
|
CZK
|
Czech koruna
|
DKK
|
Danish krone
|
DOP
|
Dominican peso
|
DZD
|
Algerian dinar
|
EGP
|
Egyptian pound
|
EUR
|
Euro
|
FJD
|
Fiji dollar
|
GBP
|
Pound sterling
|
GTQ
|
Guatemalen quetzal
|
HKD
|
Hong Kong dollar
|
HNL
|
Honduran lempira
|
HRK
|
Croatian kuna
|
HUF
|
Hungarian forint
|
IDR
|
Indonesian rupiah
|
ILS
|
Israeli new shekel
|
INR
|
Indian rupee
|
JMD
|
Jamaican dollar
|
JOD
|
Jordanian dollar
|
JPY
|
Japanese yen
|
KES
|
Kenyan shilling
|
KRW
|
South Korean won
|
KWD
|
Kuwaiti dinar
|
KYD
|
Cayman Islands dollar
|
KZT
|
Kazakhstani tenge
|
LBP
|
Lebanese pound
|
LKR
|
Sri Lankan rupee
|
MAD
|
Moroccan dirham
|
MDL
|
Moldovan leu
|
MKD
|
Macedonian denar
|
MUR
|
Mauritian rupee
|
MVR
|
Maldivian rufiyaa
|
MXN
|
Mexican peso
|
MYR
|
Malaysian ringgit
|
NAD
|
Namibian dollar
|
NGN
|
Nigerian naira
|
NIO
|
Nicaraguan cordoba
|
NOK
|
Norwegian krone
|
NPR
|
Nepalese rupee
|
NZD
|
New Zealand dollar
|
OMR
|
Omana rial
|
PEN
|
Peruvian nuevo sol
|
PGK
|
Papua New Guinean kina
|
PHP
|
Philippine peso
|
PKR
|
Pakistani rupee
|
PLN
|
Polish złoty
|
PYG
|
Paraguayan guarani
|
QAR
|
Qatari riyal
|
RON
|
Romanian new leu
|
RSD
|
Serbian dinar
|
RUB
|
Russian ruble
|
SAR
|
Saudi riyal
|
SCR
|
Seychelles rupee
|
SEK
|
Swedish krona/kronor
|
SGD
|
Singapore dollar
|
SLL
|
Sierra Leonean leone
|
SVC
|
Salvadoran colon
|
THB
|
Thai baht
|
TND
|
Tunisian dinar
|
TRY
|
Turkish lira
|
TTD
|
Trinidad and Tobago dollar
|
TWD
|
New Taiwan dollar
|
TZS
|
Tanzanian shilling
|
UAH
|
Ukrainian hryvnia
|
UGX
|
Ugandan shilling
|
USD
|
United States dollar
|
UYU
|
Uruguayan peso
|
UZS
|
Uzbekistan som
|
VEF
|
Venezuelan bolivar
|
VND
|
Vietnamese dong
|
XAF
|
CFA franc BEAC
|
XOF
|
CFA franc BCEAO
|
YER
|
Yemeni rial
|
ZAR
|
South African rand
|
|
dimensions
|
string
A comma-separated list of YouTube Analytics dimensions, such as
video
or
ageGroup,gender
. See the documentation for
channel reports
or
content owner reports
for a list of the reports that you can retrieve and the dimensions used for those reports. (The
Dimensions
document contains definitions for all of the dimensions.)
|
filters
|
string
A list of filters that should be applied when retrieving
YouTube Analytics
data. The documentation for
channel reports
and
content owner reports
identifies the dimensions that can be used to filter each report, and the
Dimensions
document defines those dimensions.
If a request uses multiple filters, join them together with a semicolon (
;
), and the returned result table will satisfy both filters. For example, a
filters
parameter value of
video==dMH0bHeiRNg;country==IT
restricts the result set to include data for the given video in Italy.
Specifying multiple values for a filter
The API supports the ability to specify multiple values for the
video
,
playlist
, and
channel
filters. To do so, specify a separated list of the video, playlist, or channel IDs for which the API response should be filtered. For example, a
filters
parameter value of
video==pd1FJh59zxQ,Zhawgd0REhA;country==IT
restricts the result set to include data for the given videos in Italy. The parameter value can specify up to 500 IDs.
When specifying multiple values for the same filter, you can also add that filter to the list of dimensions that you specify for the request. This is true even if the filter is not listed as a supported dimension for a particular report. If you do add the filter to the list of dimensions, then the API also uses the filter values to group results.
For example, suppose you retrieve a channel's
traffic source report
, which aggregates viewing statistics based on the manner in which viewers reached the channel's video content. Also suppose that your request's
filters
parameter request identifies a list of 10 videos for which data should be returned.
- If you add
video
to the
dimensions
parameter's value, the API response will provide separate traffic source statistics for each of the 10 videos.
- If you do not add
video
to the
dimensions
parameter's value, the API response will aggregate the traffic source statistics for all of the 10 videos.
|
includeHistoricalChannelData
|
boolean
Note:
This parameter only applies to
content owner reports
.
Indicates whether the API response should include channels' watch time and view data from the time period prior to when the channels were linked to the content owner. The default parameter value is
false
which means that the API response only includes watch time and view data from the dates that channels were linked to the content owner.
It is important to remember that different channels might have been linked to a content owner on different dates. If the API request is retrieving data for multiple channels and the parameter value is
false
, then the API response contains data based on the linking date for each respective channel. If the parameter value is
true
, the API response contains data matching the dates specified in the API request.
Note:
In version 1 of the API, this parameter was named
include-historical-channel-data
.
|
maxResults
|
integer
The maximum number of rows to include in the response.
Note:
In version 1 of the API, this parameter was named
max-results
.
|
sort
|
string
A comma-separated list of dimensions or metrics that determine the sort order for YouTube Analytics data. By default the sort order is ascending. The
-
prefix causes descending sort order.
|
startIndex
|
integer
The 1-based index of the first entity to retrieve. (The default value is
1
.) Use this parameter as a pagination mechanism along with the
max-results
parameter.
Note:
In version 1 of the API, this parameter was named
start-index
.
|
Standard Parameters
|
access_token
|
OAuth 2.0
token for the current user.
|
alt
|
This parameter is not supported in version 2 of the API, which only supports JSON responses.
The data format for the API response.
- Valid values:
json
,
csv
- Default value:
json
|
callback
|
Callback function.
- Name of the JavaScript callback function that handles the response.
- Used in JavaScript
JSON-P
requests.
|
prettyPrint
|
Returns response with indentations and line breaks.
- Returns the response in a human-readable format if
true
.
- Default value:
true
.
- When this is
false
, it can reduce the response payload size, which might lead to better performance in some environments.
|
quotaUser
|
This parameter was supported in version 1 of the API, which is now deprecated. This parameter is not supported in version 2 of the API.
|
userIp
|
This parameter was supported in version 1 of the API, which is now deprecated. This parameter is not supported in version 2 of the API.
|