The AdWords API can be used to access and manipulate video ads in your online campaigns. The contents of TV campaigns and video campaigns (aka AdWords for Video) are not exposed via the API.

Like all the ad types created using the Display Ad Builder, video ads are represented in the API using the TemplateAd type. Template ads provide a flexible way to introduce new ad formats without requiring the addition of new concrete ad types to the API. The IDs and field specifications for select templates are published on the Template Ads page.

The video files required for video ads cannot be uploaded via the API, and must be uploaded to your account via the web interface (see instructions). Once your video is uploaded, it is assigned a media ID. This ID, which is required to create a video ad, can be retrieved using the MediaService.get() method. Associated image files can be uploaded using the API however, either by calling MediaService.upload() beforehand or by passing the byte data directly when creating the TemplateAd.

Below is a sample SOAP request for creating a Click to Play video ad.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Header>
      <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201109">
         <authToken>...</authToken>
         <clientCustomerId>...</clientCustomerId>
         <developerToken>...</developerToken>
         <userAgent>...</userAgent>
      </RequestHeader>
   </soap:Header>
   <soap:Body>
      <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201109">
         <operations>
            <operator>ADD</operator>
            <operand>
               <adGroupId>XXXXX</adGroupId>
               <ad xsi:type="TemplateAd">
                  <url>http://www.example.com</url>
                  <displayUrl>www.example.com</displayUrl>
                  <templateId>9</templateId>
                  <templateElements>
                     <uniqueName>adData</uniqueName>
                     <fields>
                        <name>displayUrlColor</name>
                        <type>ENUM</type>
                        <fieldText>#ffffff</fieldText>
                     </fields>
                     <fields>
                        <name>startImage</name>
                        <type>IMAGE</type>
                        <fieldMedia xsi:type="Image">
                           <mediaId>XXXXX</mediaId>
                        </fieldMedia>
                     </fields>
                     <fields>
                        <name>video</name>
                        <type>VIDEO</type>
                        <fieldMedia xsi:type="Video">
                           <mediaId>XXXXX</mediaId>
                        </fieldMedia>
                     </fields>
                  </templateElements>
                  <dimensions>
                     <width>300</width>
                     <height>250</height>
                  </dimensions>
                  <name>Video Ad</name>
               </ad>
               <status>ENABLED</status>
            </operand>
         </operations>
      </mutate>
   </soap:Body>
</soap:Envelope>

YouTube Promoted Videos

Unlike the Click to Play video ad format shown above, YouTube Promoted Video ads display videos that are already hosted on YouTube. These YouTube videos must be associated with your AdWords account to be used, which at this time can only be done in the AdWords web interface. After that is done the MediaService can be used to retrieve the associated Video object, which will have the field youTubeVideoIdString populated with the ID of the associated YouTube video.

Although this ad format has primitive fields for videoThumbnail and destinationPage, these values are only used by the web interface. When creating these ads through the API you must construct and set the full destination and image URLs:

• The imageUrl field must be in the form "http://i.ytimg.com/vi/{YOUTUBE_VIDEO_ID}/{IMAGE}", where {IMAGE} is either: "default.jpg", "1.jpg", "2.jpg", or "3.jpg".
• The url field must be in either the form "http://www.youtube.com/watch?v={YOUTUBE_VIDEO_ID}" for a watch page or "http://www.youtube.com/{YOUTUBE_CHANNEL_NAME}?v={YOUTUBE_VIDEO_ID}" for the channel page.

Below is a sample request that creates a YouTube Promoted Video ad for our video Generic Selectors: One selector, many services:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Header>
      <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201109">
         <authToken>...</authToken>
         <clientCustomerId>...</clientCustomerId>
         <developerToken>...</developerToken>
         <userAgent>...</userAgent>
      </RequestHeader>
   </soap:Header>
   <soap:Body>
      <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201109">
         <operations>
            <operator>ADD</operator>
            <operand>
               <adGroupId>XXXXX</adGroupId>
               <ad xsi:type="TemplateAd">
                  <url>http://www.youtube.com/watch?v=Q5EEvnddHo4</url>
                  <displayUrl>youtube.com/googledevelopers</displayUrl>
                  <templateId>13</templateId>
                  <templateElements>
                     <uniqueName>adData</uniqueName>
                     <fields>
                        <name>imageUrl</name>
                        <type>URL</type>
                        <fieldText>http://i.ytimg.com/vi/Q5EEvnddHo4/default.jpg</fieldText>
                     </fields>
                     <fields>
                        <name>channelName</name>
                        <type>TEXT</type>
                        <fieldText>GoogleDevelopers</fieldText>
                     </fields>
                     <fields>
                        <name>videoId</name>
                        <type>VIDEO</type>
                        <fieldMedia xsi:type="Video">
                           <-- This is the mediaId obtained from the MediaService. -->
                           <mediaId>XXXXX</mediaId>
                        </fieldMedia>
                     </fields>
                     <fields>
                        <name>headline</name>
                        <type>TEXT</type>
                        <fieldText>New Selectors</fieldText>
                     </fields>
                     <fields>
                        <name>description1</name>
                        <type>TEXT</type>
                        <fieldText>One selector,</fieldText>
                     </fields>
                     <fields>
                        <name>description2</name>
                        <type>TEXT</type>
                        <fieldText>many services</fieldText>
                     </fields>
                  </templateElements>
                  <name>New Selectors</name>
               </ad>
               <status>ENABLED</status>
            </operand>
         </operations>
      </mutate>
   </soap:Body>
</soap:Envelope>

Call-to-Action Overlays

Call-to-Action overlays for YouTube Promoted Video ads can only be created using the YouTube web interface. These overlays are not exposed in either the AdWords or YouTube API.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.