Implementation and Migration: Videos

The following examples show how to use the YouTube Data API (v3) to perform functions related to videos.

Retrieve a channel's uploaded videos

YouTube Data API (v2) functionality: Videos uploaded by a specific user

This example retrieves the videos uploaded to a particular channel. The example has two steps:

YouTube Data API (v2) functionality: Related videos

To retrieve a list of videos that are related to another video, call the search.list method. Set the following parameter values in your request:

  • part: Set the parameter value to snippet.
  • type: Set the parameter value to video.
  • relatedToVideoId parameter specifies the YouTube video ID of the video for which you want to find related videos.

The request below retrieves videos related to the video of the keynote speech at the 2014 Google I/O conference, which has the video ID wtLJPvx7-ys.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &type=video
        &relatedToVideoId=wtLJPvx7-ys

YouTube Data API (v2) functionality: Standard video feed of most popular videos

Like the v2 API, the v3 API lets you retrieve a list of YouTube's most popular videos, which are selected using an algorithm that combines many different signals to determine overall popularity.

To retrieve the most popular videos list, call the videos.list method and set the chart parameter's value to mostPopular. When retrieving this list, you can also set either or both of the following parameters:

The request below retrieves the most popular sports videos in Spain:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

Upload a video

YouTube Data API (v2) functionality: Direct uploading, Browser-based uploading, Resumable uploads

Since the APIs Explorer does not support the ability to upload files, this description does not link to an executable example. The following resources will help you to modify your application so that it can upload videos using the v3 API:

  • The Uploading a Video guide provides a detailed example that explains how to upload a video using the Google APIs Client Library for Python.

  • The Resumable Uploads guide explains the sequence of HTTP requests that an application uses to upload videos using a resumable uploading process. The guide is primarily intended for developers who cannot use the Google API client libraries, some of which provide native support for resumable uploads.

  • The JavaScript example for uploading a video uses CORS (cross-origin resource sharing) to demonstrate how to upload a video file via a web page. In fact, the example demonstrates a more elegant version of the v2 API's browser-based uploading functionality because the CORS upload library that the v3 API uses naturally supports resumable uploading. In addition, the example demonstrates how to check the status of an uploaded video by retrieving the processingDetails part of the video resource as well as how to handle status changes for the uploaded video.

Related code samples: Java, JavaScript, PHP, Python, Ruby

Check the status of an uploaded video

YouTube Data API (v2) functionality: Checking the status of an uploaded video

This example shows how to check the status of an uploaded video. An uploaded video will immediately be visible in the authenticated user's uploaded videos feed. However, the video will not be visible on YouTube until it has been processed.

  • Step 1: Upload the video

    Call the videos.insert method to upload the video. If the request is successful, the API response will contain a video resource that identifies the unique video ID for the uploaded video.

  • Step 2: Check the video's status

    Call the videos.list method to check the video's status. Set the id parameter's value to the video ID obtained in step 1. Set the part parameter's value to processingDetails.

    If the request is handled successfully, the API response will contain a video resource. Check the value of the processingDetails.processingStatus property to determine whether YouTube is still processing the video. The property's value will change to something other than processing, such as succeeded or failed, when YouTube has finished processing the video.

    The request body is a video resource in which the id property specifies the video ID of the video that you are deleting. In this example, the resource also contains a recordingDetails object.

    The request below checks the status of a video. To complete the request in the APIs Explorer, you need to set the id property's value.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
            part=snippet,processingDetails
            &id=VIDEO_ID

Note: Your application could poll the API to periodically check the status of a newly uploaded video. Once the video is processed, your application could create a bulletin or proceed with another action contingent on the video's status.

Update a video

YouTube Data API (v2) functionality: Updating a video

This example shows how to update a video to add information about the time and place where the video was recorded. The example has the following steps:

  • Step 1: Retrieve the video ID

    Follow the steps above to retrieve uploaded videos for the currently authenticated user's channel. The list could be used to display a list of videos, using each video's ID as a key.

    Note: There are numerous other ways to obtain video IDs, such as retrieving search results or listing items in a playlist. However, since a video can only be updated by its owner, retrieving a list of videos owned by the user authorizing the API request is a likely first step in this process.

  • Step 2: Update a video

    Call the videos.update method to update a specific video. Set the part parameter's value to recordingDetails. (The parameter value depends on which video's metadata fields are being updated.)

    The request body is a video resource in which the id property specifies the video ID of the video that you are updating. In this example, the resource also contains a recordingDetails object.

    The sample resource below indicates that the video was recorded on October 30, 2013, in Boston:

    {
      "id": "VIDEO_ID",
      "recordingDetails": {
        "location": {
          "latitude": "42.3464",
          "longitude": "-71.0975"
        }
        "recordingDate": "2013-10-30T23:15:00.000Z"
      }
    }

    To complete the request in the APIs Explorer, you need to set the id property's value.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
            part=snippet

Upload a custom thumbnail image and set it for a video

New in v3: This functionality is new in the v3 API.

You can use the v3 API's thumbnails.set method to upload a custom thumbnail image and set it for a video. In your request, the videoId parameter's value identifies the video for which the thumbnail will be used.

This query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to upload media files, which is a requirement for this method.

Related code samples: PHP, Python

Delete a video

YouTube Data API (v2) functionality: Deleting a video

This example shows how to delete a video. The example has the following steps:

  • Step 1: Retrieve the video ID

    Follow the steps above to retrieve uploaded videos for the currently authenticated user's channel. The list could be used to display a list of videos, using each video's ID as a key.

    Note: There are numerous other ways to obtain video IDs, such as retrieving search results or listing items in a playlist. However, since a video can only be deleted by its owner, retrieving a list of videos owned by the user authorizing the API request is a likely first step in this process.

  • Step 2: Delete a video

    Call the videos.delete method to delete a specific video. In the request, the id parameter specifies the video ID of the video that you are deleting. The request must be authorized using OAuth 2.0. If you are testing this query in the APIs Explorer, you will need to substitute a valid video ID for the id parameter value.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
            id=VIDEO_ID
    

Report an abusive video

YouTube Data API (v2) functionality: Adding a complaint

This example shows how to report a video that contains abusive content. The example has the following steps:

  • Step 1: Retrieve IDs that explain why the video is being reported

    Send an authorized request to the videoAbuseReportReasons.list method to retrieve a list of valid reasons for flagging a video. The sample videoAbuseReportReason resource below contains information for flagging a video that contains spam or misleading content.

    {
      "kind": "youtube#videoAbuseReportReason",
      "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
      "id": "S",
      "snippet": {
        "label": "Spam or misleading",
        "secondaryReasons": [
          {
            "id": "27",
            "label": "Spam or mass advertising"
          },
          {
            "id": "28",
            "label": "Misleading thumbnail"
          },
          {
            "id": "29",
            "label": "Malware or phishing"
          },
          {
            "id": "30",
            "label": "Pharmaceutical drugs for sale"
          },
          {
            "id": "31",
            "label": "Other misleading info"
          }
        ]
      }
    }

    As shown in the resource, this reason is associated with a list of secondary reasons. When flagging a video for containing spam, you need to provide the ID for the reason and are strongly encouraged to provide a secondary reason as well.

  • Step 2: Flag the video for abusive content

    Send an authorized request to the videos.reportAbuse method to actually report the video. The request body is a JSON object that identifies both the video being flagged and the reason it is being flagged. As noted in step 1, for some types of reasons, a secondary reason is supported and strongly encouraged.

    The JSON object's videoId property identifies the video that is being flagged.

    The sample JSON object below flags a video for containing spam or misleading content and, more specifically, for using a misleading thumbnail image. As shown in the sample JSON object above, the ID for Spam or misleading content is S. The ID for a Misleading thumbnail is 28.

    {
      "videoId": "VIDEO_ID",
      "reasonId": "S",
      "secondaryReasonId": "28",
      "comments": "Testing the video flagging feature.",
      "language": "en"
    }

    The videos.reportAbuse request must be authorized using OAuth 2.0. The link below loads the JSON object above in the APIs Explorer. To test the query, you need to substitute a valid video ID for the videoId property value. Please remember that submitting this request will actually flag the video.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse

Send feedback about...

YouTube Data API
YouTube Data API