Migration Guide

Note: The YouTube Analytics API (v1) has been deprecated as of November 1, 2018. If you have not done so already, please update your client to work with version 2 of the API to avoid service interruptions. See the API's migration guide for details.

This guide explains how to migrate an application from version 1 to version 2 of the YouTube Analytics API. The remainder of this document uses the terms "v1" and "v2" to refer to the two API versions.

Code changes

API version and base URL changes

Your code identifies the API that it calls by the API's name (youtubeAnalytics) and version (v1 or v2).

To call the v2 API instead of the v1 API, you likely need to make the following code changes:

  • If your code explicitly specifies API endpoints, then you need to update it to use the correct base URLs. In v1, the base URL is:

    https://www.googleapis.com/youtube/analytics/v1

    In v2, the base URL is:

    https://youtubeanalytics.googleapis.com/v2
  • If your code uses one of the API client libraries, then you likely need to modify your code to specify the new API version. Depending on which client library you are using, you might also need to update it to call the updated base URLs. Changes for client library users are summarized in the Updating client library code section below.

Parameter name changes

In the v1 API, several parameters for the reports.query method have names that contain hyphens, such as start-date. In the v2 API, the parameter names use camel case rather than hyphens to separate words, so the new name of the start-date parameter is startDate.

The following parameters are affected:

v1 name v2 name
end-date endDate
include-historical-channel-data includeHistoricalChannelData
max-results maxResults
start-date startDate
start-index startIndex

As such, you need to modify your code to use the new parameter names. (The startDate and endDate parameters are required in v2 API calls, just as start-date and end-date were required in v1.)

Some client libraries, such as Python, did not use parameter names with hyphens in v1 and used names with underscores instead, such as start_date and end_date. The names with underscores also need to be updated to the camel case names to call the v2 API.

Updated API endpoint for batch requests

The v2 API does not support batch requests sent to Google's global HTTP batch endpoint (www.googleapis.com/batch). If you are sending batch requests in the v2 API, use the endpoint https://youtubeanalytics.googleapis.com/v2 instead.

Note that the v2 API's batch endpoint supports multiple requests as long as they are all YouTube Analytics API requests. For example, the batch cannot include some YouTube Data API requests and some YouTube Analytics API requests. It can, however, be comprised of requests to different YouTube Analytics API methods. The ability to submit a batch that included requests to different APIs had been supported via the global batch endpoint in the v1 API, and that functionality is now deprecated.

If you are using a client library to make batch requests, the batch requests will be sent to the correct endpoint as long as you are using the latest version of those client libraries.

Updating client library code

The tabs below show the likely code changes for different client libraries:

JavaScript
  1. Modify the API discovery document URL to refer to the correct API version as shown below:

    // API v1:
    var discoveryUrl = (
        'https://www.googleapis.com/discovery/v1/apis/youtubeAnalytics/v1/rest');
    
    // API v2:
    var discoveryUrl = (
        'https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2');
  2. Update any code that calls the deprecated version of the gapi.client.load function to use API discovery documents instead. The deprecated function supports parameters for specifying an API name, an API version, and a callback function. It is called like this:

    gapi.client.load('youtubeAnalytics', 'v1', function() { ... });

    Instead, your code should specify an API discovery document URL when calling gapi.client.load:

    gapi.client.load('https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2');
  3. Modify parameter names that contained hyphens in the v1 API to use camel case in v2 API calls. All of the affected parameters, which are listed in the table below, are used in the reports.query method.

    v1 parameter v2 parameter
    end-date endDate
    include-historical-channel-data includeHistoricalChannelData
    max-results maxResults
    start-date startDate
    start-index startIndex
  4. If your code uses the gapi.client.request method to make API calls, modify API paths to use the correct API version. Note that in the v2 API, the API itself is identified in the URL host and does not need to be specified in the path:

    // API v1 (hostname is https://www.googleapis.com):
    gapi.client.request('method': 'GET',
                        'path': '/youtubeAnalytics/v1/reports',
                        'params': {...});
    
    // API v2 (hostname is https://youtubeanalytics.googleapis.com):
    gapi.client.request('method': 'GET',
                        'path': '/v2/reports',
                        'params': {...});
Python
  1. Change the API version specified in your code from v1 to v2:

    API_SERVICE_NAME = 'youtubeAnalytics'
    API_VERSION = 'v2'
    SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']
    def get_service():
      flow = InstalledAppFlow.from_client_secrets_file(/path/to/client_secret.json, SCOPES)
      credentials = flow.run_console()
      return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)
    
  2. Update any parameter names that use snake case to use lower camel case instead. The table below lists parameter names that changed in the Python client library between the v1 and v2 APIs:

    Parameters by method
    reports.query
    • end_date changes to endDate
    • include_historical_channel_data changes to includeHistoricalChannelData
    • max_results changes to maxResults
    • start_date changes to startDate
    • start_index changes to startIndex

Deprecated features

CSV response format (alt request parameter)

In the v1 API, the reports.query method supports the alt parameter, which lets you choose to format the API response data as JSON (alt=json) or comma-separated values (alt=csv). In the v2 API, responses are always in JSON format. As such, if you are currently retrieving CSV reports with the v1 API, you either need to modify your code to process JSON reports or convert the JSON reports to CSV before processing them.

quotaUser and userIp request parameters

In the v1 API, the reports.query method supports the quotaUser and userIp query parameters, which enable you to cap the number of API requests made per user per second from a server-side application. Normally, a request from a server-side application is listed as coming directly from the server-side machine itself, and both of these request parameters provide a way to identify the user responsible for the request.

However, neither parameter is supported in the v2 API, so all API requests are listed as coming directly from the server-side machine itself.

Global batch requests

The v2 API does not provide a batch endpoint that supports batches comprised of requests to different APIs. (A batch can be comprised of requests to different methods of the same API, however.) This deprecation is not specific to the YouTube Analytics API as Google is deprecating the global batch endpoint across all of its APIs. The Google Developers blog post from March 22, 2018, provides more detail about this deprecation.

JSON-RPC protocol support

The v2 API does not support the JSON-RPC protocol, which was supported in API v1. Again, this deprecation is not specific to the YouTube Analytics API and additional details about the deprecation are in the Google Developers blog post from March 22, 2018. Indeed, very few API clients use this feature, but you can learn how to identify whether your app uses it and how to migrate away from it using steps explained in the blog.