Note:
The YouTube Content ID API is intended for use by YouTube content partners and is not accessible to all developers or to all YouTube users. If you do not see the YouTube Content ID API as one of the services listed in the
Google API Console
, see the
YouTube Help Center
to learn more about the YouTube Partner Program.
This page lists YouTube Content ID API changes and documentation updates.
November 10, 2023
The
videoAdvertisingOption
resource's
adFormats[]
field has been updated so that
third_party_ads
is the only valid value for that field. The following ad formats are no longer supported:
instream_trueview
,
instream_standard
,
display
,
preroll
,
postroll
. See
support article
for more details.
June 1, 2023
Note:
This is a deprecation announcement.
This update includes the following changes:
December 20, 2022
The definition of the
assetSearch.list
method's
ownershipRestriction
query parameter has been updated to clarify that if that parameter's value is
none
,
the
metadataSearchFields
parameter value must also use at least one ID filter.
This documentation change does not reflect a change in API behavior.
November 9, 2022
The documentation for the
asset.get
and
asset.list
methods has been
updated to clarify how multiple values are supported for:
September 28, 2022
Licensability information has been added to the
asset resource
.
July 18, 2022
The documentation for the
claimSearch.list
method's
inactiveReasons
has been updated to reflect improvements for consistency with YouTube Studio:
- Studio had previously removed support for
Audio Swap
and
Song Erase
.
The corresponding API values,
audio_removed
and
song_erased
, were
silently ignored and have now been undocumented.
channel_whitelisted
has been replaced with
channel_allowlisted
.
The previous value is no longer documented but is still supported.
- The values
closed_disabled_monetization
,
closed_manually
,
closed_no_adsense
,
closed_own_video_match
,
reference_removed
,
replaced
, and
video_modified
are now
supported.
June 14, 2022
The
assetSearch
resource
documentation has been updated to reflect the two new
properties:
isrcs[]
and
iswcs[]
. The new
isrcs[]
and
iswcs[]
property values each contain an array of string
values with each value specifying an ISRC or ISWC, as appropriate, that maps to the asset
identified by the search result.
The new properties are recommended over the
isrc
and
iswc
properties
already included in
assetSearch
resources because the new properties provide more
accurate data. Whereas the new properties potentially list an array of string values, the
isrc
and
iswc
properties each identify only one ISRC or ISWC code
associated with the search result.
May 12, 2022
The links to client libraries were updated to point to the standard Google APIs client libraries. Pre-generated bindings for PHP were updated.
May 3, 2022
The
claimSearch.list
method's
status
parameter now supports more filters based on potential claim details.
May 2, 2022
The documentation for the
assetSearch.list
method's
Response
has been updated to reflect improvements for consistency with
AIP-158
:
- The description of
pageInfo.totalResults
explicitly mentions that the value is an estimate and not the actual value
- Fields
pageInfo.resultsPerPage
and
pageInfo.startIndex
have been removed
April 25, 2022
The documentation for the
assetLabels.list
resource has been updated to clarify the meaning of
labelPrefix
and
q
request parameters, and to document that the request / response support pagination.
December 8, 2021
The documentation for the
claimSearch.list
resource has been updated to properly reflect the two use cases this method covers:
- Search by ID (asset, reference or video) or query string
- Search by claim creation date, modification date, or status
Each use case supports a different set of query parameters. The
claimSearch.list
method's documentation has been updated to explain which parameters are supported for each use case.
November 17, 2021
This update includes the following changes:
- The
claims.update
method now supports the ability to update an inactive or potential claim's status to
active
. The definition of the
claim
resource's
status
property provides more details.
- The documentation for the
claim
and
claimSearch
resources has been updated to reflect the addition of the new
studioInfo
object, which contains links to YouTube Studio pages related to the claim.
- The list of values supported for the
claimSearch.list
method's
origin
parameter has changed. The parameter now supports four additional values:
batchTool
,
inProductShorts
,
melodyMatch
, and
youTubeAdmin
. In addition, the
dropboxUpload
and
webUpload
values are no longer supported.
February 26, 2021
The documentation for the
claimSearch.list
method's
videoId
parameter has been updated to note that the parameter value now accepts a maximum of 10 comma-separated video IDs. The API will return a
badRequest
error ?
400
HTTP response code ? if the value contains more than 10 video IDs.
December 6, 2018
Note:
This is a deprecation announcement.
The API documentation has been updated to remove references to the
contentOwnerAdvertisingOptions
resource and its methods. These methods were very minimally used, and API users that did use them have been contacted separately prior to this announcement.
March 21, 2018
This update contains the following changes:
-
The
metadataMine.artist
property must now be set any time you
insert
,
update
, or
patch
a music video or sound recording asset. The API now returns an error if the property is not set for those resource types. In addition, note that the
metadataMine.artist
property is only supported for music video and sound recording artists.
July 24, 2017
This update contains the following changes:
-
The new
package
resource represents a group of files delivered via the web, SFTP, or another delivery mechanism. The API's supports two methods for this resource:
- The
package.insert
method validates and uploads a metadata-only package containing exactly one metadata file.
- The
package.get
method retrieves information about a previously uploaded package.
-
For the
validator.validate
method, the definition of the
uploaderName
property has been updated to note that the value does not identify the content partner uploading the data but rather a value like
web-google
or
yt-google
that identifies the specific uploader account that the content owner is using.
-
The
reference
resource's
status
property no longer uses the value
duplicate_on_hold
to indicate that a reference is a duplicate of another reference. Instead, if a reference is a duplicate, the value of the
status
property is now set to
inactive
, and the value of the
statusReason
property is
REASON_DUPLICATE_FOR_OWNERS
.
However, as before, the resource's
duplicateLeader
property is only populated if the reference is a duplicate. If it is set, then that property's value identifies the duplicated reference.
April 17, 2017
This update contains the following changes:
-
The new
assetShare
resource which is only relevant to composition assets, identifies a relationship between two representations of an asset resource. These representations reflect a
new publishing data model
designed to provide more transparency into and control over how your rights are associated with sound recording assets.
In the new model, each sound recording maps to exactly one, unique asset, which is called a
composition view
. That asset's metadata represents the canonical set of information that YouTube displays about the composition rights associated with a given recording, and it may synthesize information from multiple data providers.
In addition, each owner of the composition has its own
composition share
asset. The composition share represents the information that a particular publisher provided for a composition asset. The composition share can be associated with many sound recordings.
The
assetShare
resource identifies a relationship between a composition view and a composition share. The new
assetShares.list
method lets you do either of the following:
- Provide the ID of a composition view and retrieve the corresponding composition share owned by the partner authorizing the request, if such a share exists.
- Provide the ID of a composition share owned by the content partner and retrieve a list of all of the composition views to which that share is linked.
-
The new
Managing composition assets
guide explains how different API methods handle requests depending on whether the asset IDs submitted to those methods identify composition views or composition shares.
-
The
contentOwnerAdvertisingOptions
resource's new
claimedVideoOptions.autoGeneratedBreaks
property indicates whether YouTube should automatically generate ad breaks in claimed videos that are more than 10 minutes long. While the property affects all of the content owner's videos that are more than 10 minutes long, if a video has multiple claims, the first partner that claims a video sets the default behavior for this property in relation to that video.
August 11, 2016
This update contains the following changes:
-
The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the
YouTube Engineering and Developers Blog
, provides a rich set of updates to the current Terms of Service. In addition to the
Updated Terms
, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.
The full set of new documents is described in the
revision history for the Updated Terms
. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.
May 31, 2016
This update contains the following changes:
March 28, 2016
This update contains the following changes:
February 3, 2016
This update contains the following changes:
-
Updates to existing resources and methods
-
The API now supports product listing ads. Product listing ads highlight products that are related to or are featured in a video's content. These ads are
sponsored cards
that display during the video. The cards are added automatically by the ad system. Viewers see a teaser for the card for a few seconds and can also click the icon in the top right corner of the video to browse the video's cards.
As a result of this change,
product_listing
can now be included in the following properties' values:
-
The
assetSearch.list
method's new
createdBefore
and
createdAfter
instruct the API to only return assets created before and/or after a certain date.
-
In the API response to an
assetSearch.list
request, the
type
property now supports the value
art_track_video
. The
YouTube Help Center
provides more information about art track videos.
-
The
claimSearch.list
method supports the following new parameters:
Parameters
|
referenceId
|
This filter parameter specifies the YouTube reference ID of the reference for which you are retrieving claims.
|
inactiveReasons
|
This optional parameter lets you restrict the API response to only include inactive claims based on specified reasons why the claims became inactive. The parameter definition lists the types of inactive claims for which you can search.
|
partnerUploaded
|
This optional Boolean parameter lets you specify that the API response should only include either partner-uploaded or non-partner-uploaded claims.
|
-
The
reference
resource's new
references#origination
object contains information that describes the source of the reference.
-
The
references.insert
method now supports the ability to upload references generated using YouTube's gfp_gen software. If you provide a pre-generated fingerprint, set the
fpDirect
property value to
true
in the uploaded
reference
resource.
Note that with this change, the API no longer returns an error if you try to set the
fpDirect
property when uploading a reference.
-
New and updated errors
The documentation now lists errors returned by the
whitelist
resource's methods.
In addition, the following table identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type. Please refer to the error documentation for each method or to the
errors
page for more information.
Errors
|
badRequest (400)
|
inappropriateCampaignTarget
The
campaigns.insert
and
campaigns.update
methods return this error if a campaign attempts to feature a video that may be inappropriate for some users. To address the error, please choose different content to feature.
|
badRequest (400)
|
canNotCreatePartnerUploadedClaim
OnCompositionOrSoundRecordingAssets
The
claims.insert
method returns this error if you try to create a partner-uploaded claim with a composition or sound recording asset.
|
badRequest (400)
|
existingSoundRecordingOrMusicVideoClaim
The
claims.insert
method returns this error if a claim already exists for recorded music on the specified video. Direct composition claims cannot be added via the API.
|
badRequest (400)
|
asset_id
The
references.insert
method returns this error if the request attempted to create a reference through a file but the request did not specify an assetId.
|
badRequest (400)
|
canNotBeActivated
The
references.update
method returns this error if the reference cannot be activated, possibly due to the reference's status or to ownership conditions.
|
badRequest (400)
|
videoNotClaimed
The
videoAdvertisingOptions.get
method returns this error if you have not claimed the video for which you you are trying to retrieve advertising options, thereby making the requested information unavailable to you.
|
December 18, 2015
European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the
EU User Consent Policy
. We have added a notice of this requirement in our
YouTube API Terms of Service
.
April 21, 2015
This update contains the following changes:
-
The new
campaign
resource represents a specific
content owner campaign
, which allows the content owner to use annotations to promote content on claimed, user-uploaded videos. For example, a content owner could create a campaign that adds links to a movie's watch page for any claimed, user-uploaded videos that contain scenes from that movie.
The API supports methods to
get
,
list
,
insert
,
update
,
patch
, and
delete
campaign
resources.
-
The API supports several new errors for the new
campaigns.get
,
campaigns.insert
,
campaigns.update
, and
campaigns.delete
methods.
March 30, 2015
This update contains the following changes:
-
Updates to existing resources and methods
-
The
assetSearch.list
method's new
isrcs
parameter lets you specify a list of up to 50 ISRCs. The API response will include assets associated with those ISRCs.
-
The
claimHistory
resource's
event[].reason
property supports the following new values. Each reason explains why a particular event related to the claim occurred:
- closed_audio_claim_on_visual_reference
- closed_partner_exclusion
- closed_reference_conflict
-
The
claimSearch.list
method's new
sort
parameter specifies the method that will be used to order resources in the API response. By default, resources are sorted in reverse chronological order (from newest to oldest) based on the dates they were created. You can also sort resources from highest to lowest number of views for the claimed content.
Note that if the
claimSearch.list
request also sets the
status
parameter value to either
appealed
,
disputed
,
pending
,
potential
, or
routedForReview
, then results are sorted by the time that the claim review period expires.
-
The
ownership.update
and
ownership.patch
methods now correctly list all of the properties that can be updated when calling these methods. This change represents a correction to the API documentation and does not identify a change to API functionality.
-
The
fetchMatchPolicy
parameters for the
assets.get
and
assets.list
methods now list
effective
as a supported value. The value instructs the API server to retrieve the match policy that YouTube applies for the asset.
-
The
id
parameters for the
assets.list
,
claims.list
,
contentOwners.list
,
policies.list
,
publishers.list
, and
references.list
methods all now note that their parameter values can contain a maximum of 50 comma-separated IDs.
-
New and updated errors
The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type.
Please refer to the error documentation for each method or to the
errors
page for more information.
Error type
|
Error detail
|
Description
|
badRequest (400)
|
tooManyIsrcs
|
The
assetSearch.list
method returns this error if the
isrcs
parameter specifies more than 50 ISRCs.
|
badRequest (400)
|
videoIsPrivate
|
The
claims.insert
method returns this error if you try to claim a private video. You can only claim a video if its privacy status is
public
or
unlisted
.
|
notModified (304)
|
blockOutsideOwnershipUnchanged
|
The
claims.update
method returns this error if the
blockOutsideOwnership
flag on the claim was not successfully modified. There are several reasons why this error might occur. A common example is because the specified modification has no effect on the claimed video.
|
November 7, 2014
This update contains the following changes:
-
Updates to existing resources and methods
-
The
claimSearch.list
method's
status
parameter now supports a value of
routedForReview
. This value restricts results to claims that require manual review based on a rule in an asset's match policy.
-
The
claimHistory
resource's
event[].reason
property supports the following new values. Each reason explains why a particular event related to the claim occurred:
- closed_invalid_reference_segment
- closed_noadsense
- suspended_monetization_on_channel
- video_content_modified
-
The
claim
resource's
origin.source
property, which identifies the source of a claim, now supports the value
melodyMatch
. A melody match claim indicates that the claimed video shares a musical composition with a reference.
-
The
references.insert
method's documentation has been updated to properly reflect that the API uses two different endpoints for that method. This does not represent a change in API functionality, but rather a correction to the existing documentation.
-
If the request is uploading a new reference file, the correct endpoint is:
POST https://www.googleapis.com/upload/youtube/partner/v1/references
-
If the request is creating a reference using a claimed video as the reference content, the correct endpoint is:
POST https://www.googleapis.com/youtube/partner/v1/references
-
New and updated errors
The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type.
Please refer to the error documentation for each method or to the
errors
page for more information.
Error type
|
Error detail
|
Description
|
badRequest (400)
|
invalidLabelName
|
The
assets.insert
,
assets.update
, and
assetLabels.insert
methods return this error if an asset label's name is invalid. Label names must be between two and 30 characters. They may not contain angled brackets, commas, colons, ampersands, or the vertical pipe character (|).
|
badRequest (400)
|
ownerHaveMaximumNumberOfLabels
|
The
assets.insert
,
assets.update
, and
assetLabels.insert
methods return this error if a content owner has already defined 2500 unique asset labels, which is the maximum number currently allowed.
|
badRequest (400)
|
tooManyLabelsOnOneAsset
|
The
assets.insert
and
assets.update
methods return this error if an asset is already associated with 30 asset labels, which is the maximum number currently allowed.
|
badRequest (400)
|
channelMonetizationSuspended
|
The
claims.insert
and
claims.update
methods return this error if a video's channel is suspended for partner claims.
|
badRequest (400)
|
channelNotActive
|
The
claims.update
method returns this error if a video's channel is not active.
|
-
The
assets.insert
and
assets.update
methods no longer return a
badRequest
error for some assets if the resource in the request body does not contain the
metadataMine.contentType
property.
September 23, 2014
This update contains the following changes:
-
Content Owner ID changes
The content owner ID changes announced in the revision history on July 9, 2014, have gone into effect. As a result of this change, the API now returns a generated, unique ID to identify the content owner associated with either the authenticated user or a resource managed through the API. Previously, the API returned a human-readable name as the ID, such as "qrs_network."
This change affects the following API functionality and will likely impact partners who have hard-coded Partner Codes in their applications.
- The API now returns the new ID as the value of resource properties that previously returned the Partner Code, such as the
contentOwner
resource's
id
property.
- All of the API's methods support the
onBehalfOfContentOwner
parameter, which identifies the content owner on whose behalf the API request is being made. Following the change, the parameter should be set to the new ID instead of the Partner Code. To prevent code breakages, the parameter will accept either value during a transition period.
- Following the change, the
contentOwners.list
method's
contentOwnerId
parameter should specify the new ID instead of the Partner Code.
-
Updates to existing resources and methods
-
The
assetSearch.list
method's new
metadataSearchFields
parameter lets you specify asset metadata fields that you want to search as well as the values that you want to search for in those fields. The parameter value is a comma-separated list of field and value pairs; within a pair, the field and value are separated by a colon.
-
The
claim
resource's new
appliedPolicy
object specifies the policy that YouTube actually applies for the claim. The object's value is a
policy
resource. That resource contains policy information for the countries where the content owner that submitted the request owns the claimed asset.
The applied policy can differ from the policy that the content owner defined in two ways:
-
It accounts for policies set by other owners who have partial ownership of the claimed asset in some of the same territories as the content owner that submitted the API request.
-
It accounts for YouTube administrative policies that apply in territories where the content owner owns the claimed asset.
-
The
claimHistory
resource's new
uploaderChannelId
property identifies the channel ID of the channel to which the claimed video was uploaded.
September 8, 2014
This update contains the following changes:
-
New resources and methods
-
The new
assetLabel
resource identifies a text label that can be assigned to an asset. Asset labels let you place assets into custom categories, making it easier to organize your asset library. You can search for assets based on their labels, which can also simplify use cases that require you to update specific groups of assets.
- The
assetLabels.list
method lets you retrieve a list of a content owner's labels.
- The
assetLabels.insert
method lets you create a new asset label. You can also create new labels by calling the
assets.update
method and updating the labels for an asset. The API server will automatically create a new
assetLabel
resource for any previously undefined label.
-
Updates to existing resources and methods
-
The
asset
resource's
label[]
property has been updated to note that you can call the
assets.update
method to update an asset's labels. However, you cannot set an asset's labels when calling the
assets.insert
method.
The new
Using Asset Labels
guide explains how to create and retrieve asset labels as well as how to update an asset's labels or search for assets associated with particular labels.
-
New and updated errors
The API supports several new errors for the new
assetLabels.list
and
assetLabels.insert
methods.
July 9, 2014
This update contains the following changes:
-
Content Owner ID changes
Historically, the API has used a human-readable Partner Code, such as "qrs_network", to uniquely identify the content owner associated with either the authenticated user or a resource managed through the API. In Q3 2014, the API will switch to instead use a unique 22-character ID to identify content owners. The change affects the following API functionality and will likely impact partners who have hard-coded Partner Codes in their applications.
- The API will return the 22-character ID as the value of resource properties that previously returned the Partner Code, such as the
contentOwner
resource's
id
property.
- All of the API's methods support the
onBehalfOfContentOwner
parameter, which identifies the content owner on whose behalf the API request is being made. Following the change, the parameter should be set to the 22-character ID instead of the Partner Code. To prevent code breakages, the parameter will accept either value during a transition period.
- Following the change, the
contentOwners.list
method's
contentOwnerId
parameter should specify the 22-character ID instead of the Partner Code.
-
Updates to existing resources and methods
-
An
asset
resource now supports the
label
property, which specifies a list of asset labels associated with the asset. You can apply a label to multiple assets to group them. You can use the labels as search filters to perform bulk updates, to download reports, or to filter YouTube Analytics.
-
The
assetSearch.list
method now supports the following optional parameters:
labels
: Restricts results to only include assets that are associated with the specified labels. By default, the API returns assets that match all of the specified labels. However, you can use the
includeAnyProvidedLabel
parameter to instruct the API to return assets that match any of the specified labels.
includeAnyProvidedLabel
: Used in conjunction with the
labels
parameter, this parameter instructs the API return assets that are associated with any of the labels specified in the
labels
parameter value.
-
A
claimHistory
resource now contains the following new properties:
-
The
claimSearch.list
method now supports the following optional parameters:
createdAfter
: Restricts results to only include claims created after the specified date.
createdBefore
: Restricts results to only include claims created before the specified date.
includeThirdPartyClaims
: Used in conjunction with the
videoId
parameter, this parameter indicates whether to include third-party claims in the API results.
-
More detailed error information
The
error documentation
now specifies the HTTP response code for each error type.
-
New and updated errors
The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type. For example, a
required
error is returned if you try to insert an
asset
resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.
Please refer to the error documentation for each method or to the
errors
page for more information.
Method
|
Errors
|
assetSearch.list
|
invalidValue
– The API does not support the ability to search for show or season assets. Change the value of the
type
parameter to a supported value.
|
assets.insert
|
conflict
– Too many assets with the same identifier (e.g. custom ID, ISRC, etc.) already exist.
conflict
– Too many copies of the specified asset already exist.
invalidValue
– The user calling the API does not have permission to create assets of the specified type.
|
assets.patch
assets.update
|
badRequest
– The API does not support the asset type conversion you have attempted.
|
claimSearch.list
|
|
ownership.patch
ownership.update
|
badRequest
– You cannot update ownership of an art track asset.
|
references.patch
references.update
|
badRequest
– The reference is in an invalid state for the operation you are attempting.
|
February 3, 2014
This update contains the following changes:
-
Updates to existing resources and methods
-
An
asset
resource can now have a
type
value of
art_track_video
.
-
A
claimSearch
resource now includes the following new properties:
- The
origin
object contains information that describes the manner in which the claim was created.
- The
thirdPartyClaim
property contains a Boolean value that indicates whether the claim was made by a content owner other than the one associated with the user performing the search.
-
The
claimSearch.list
method now supports the following optional parameters:
contentType
: Restricts results to only include either audio-only claims, video-only claims, or audiovisual claims.
origin
: Specifies one or more claim origins, such as
descriptiveSearch
or
videoMatch
, for which you want to find claims.
status
: Restricts results to only include claims that have the specified status.
-
The
claim
resource's
status
property now supports the following additional values:
appealed
,
disputed
,
potential
,
takedown
, and
unknown
.
-
The
claim
resource's new
blockOutsideOwnership
property indicates whether the claimed video should be blocked in territories where it is not explicitly owned. By default, a claimed video would still be viewable in countries where ownership data had not been defined for the asset associated with the claim.
-
The
contentOwnerAdvertisingOption
resource's new
allowedOptions.autoGeneratedBreaks
property indicates whether the partner can opt to show midroll, in-stream ads at break times automatically determined by YouTube.
-
The
contentOwners.list
method can now be called with an authorization token that specifies the
https://www.googleapis.com/auth/youtubepartner-content-owner-readonly
scope.
-
The
policy
resource's new
timeUpdated
property specifies the time when the policy was last updated.
-
The
policies.list
method now supports an optional
sort
parameter, which can be used to specify that results should be sorted in ascending or descending order of the time they were last updated.
-
The
referenceConflict
resource's new
expiryTime
property specifies the time when the review period for the reference conflict will end, causing the conflict to expire.
-
The
videoAdvertisingOption
resource's new
autoGeneratedBreaks
property indicates whether the video should show midroll, in-stream ads at break times automatically determined by YouTube.
-
New and updated errors
The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type. For example, a
required
error is returned if you try to insert an
asset
resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.
Please refer to the error documentation for each method or to the
errors
page for more information.
Method
|
Errors
|
assets.insert
assets.update
|
badRequest
– The API does not support write operations on art track assets.
|
claimSearch.list
|
invalidValue
– The
pageToken
parameter in the request specifies an invalid page token.
|
claims.insert
|
badRequest
– The claim you are trying to create is invalid because the video's channel is not active.
badRequest
– The video you are trying to claim is exempt from a takedown policy. For inquiry, please contact copyright@youtube.com
badRequest
– Your request cannot be processed because you cannot create a third-party claim on the specified video.
conflict
– YouTube cannot create the requested claim because the video has countered a takedown notice.
conflict
– YouTube cannot create the requested claim because the video has an active takedown claim.
|
references.insert
|
badRequest
– The claimed video that you are trying to use was deleted or rejected, or its processing failed.
|
-
The
contentOwnerNotProvided
and
internalError
errors, which are not specific to a particular API method, are no longer listed on every method page. Their descriptions can still be found in the
General errors
section of the API's error documentation.
September 12, 2013
This update contains the following changes:
July 16, 2013
This update contains the following changes:
-
New resources and methods
-
The new
claimHistory.get
method lets you identify and retrieve information about a specific claim. The returned
claimHistory
resource contains a list of events related to the claim, such as the claim being created, updated, disputed, or closed.
-
The new
claimSearch.list
method lets you search for claims that meet any or all of the following criteria:
- The claims are associated with a specific asset.
- The claims are associated with a specific video.
- The claims match a query string provided in the request.
Each
claimSnippet
resource in the API response contains details about a claim, including that claim's unique claim ID, its status, its type (
audio
,
video
, or
audiovisual
), and the asset and video associated with the claim. The resource also specifies the number of views for the claimed video and the claimed video's title.
-
Updates to existing resources and methods
-
The documentation now lists the supported values for properties that have a set of enumerated values. Such properties include the
asset
resource's
type
property and the
claim
resource's
status
property.
-
For the
assets.get
and
assets.list
methods, the API now supports comma-separated values for the
fetchMetadata
and
fetchOwnership
request parameters, enabling you to retrieve multiple sets of metadata or ownership data.
The list below explains the corresponding changes to the
asset
resource's structure as well as the impacts of those changes on API methods that
get
,
list
,
insert
,
update
, or
patch
asset
resources.
-
The
metadata
object has been deprecated and replaced by the
metadataMine
and
metadataEffective
objects. The new objects allow an
asset
resource to include both the set of metadata provided by the content owner making the API request as well as the canonical set of metadata that YouTube has determined is the most accurate, complete set of metadata for the asset.
-
Similarly, the
ownership
object has been replaced with the
ownershipMine
and
ownershipEffective
objects.
-
The
matchPolicy
object has been replaced with the
matchPolicyMine
object. (The API does not currently support the ability to retrieve the effective match policy for an asset.)
Note:
To ensure backward compatibility, if only one metadata version, one set of ownership data, or one match policy is requested for an asset, the API response will include the deprecated object as well as the newly supported object. For example, if a request sets the
fetchMetadata
parameter to
mine
, the API response will contain a
metadata
object and a
metadataMine
object, both of which will contain the same data. (The ability to set
fetchMetadata=mine
was supported prior to the feature update enabling you to retrieve multiple metadata versions.)
However, if the
fetchMetadata
parameter is set to
mine,effective
, the API response will contain
metadataMine
and
metadataEffective
objects, but it will not contain a
metadata
object. (The ability to set
fetchMetadata=mine,effective
was not supported prior to this feature update, so there is no need to return the
metadata
object for backward compatibility.) The same principle also applies to the
fetchOwnership
and
fetchMatchPolicy
parameters.
Similarly, for backward compatibility, a request to
insert
,
update
, or
patch
an
asset
resource can include either the
metadataMine
object or the
metadata
object. The same principle applies to setting an
asset
resource's ownership data or match policy.
-
The
claims.list
method's
assetId
,
q
, and
videoId
parameters have been deprecated. To search for claims using any of these criteria, use the
claimSearch.list
method, which supports all of those parameters.
-
In an
ownership
resource, the values of the
general[].ratio
,
performance[].ratio
,
synchronization[].ratio
, and
mechanical[].ratio
properties all now have a content format of
double
instead of
integer
.
-
The definition of the
policy
resource's
rules[].action
property now lists valid values for that property:
block
,
monetize
,
takedown
, and
track
. However, note that you cannot use the API to apply a takedown policy to a claim.
-
The
reference
resource's new
claimId
property is present if the reference was created by associating an asset with an existing YouTube video that was uploaded to a YouTube channel linked to your CMS account. In that case, this field contains the ID of the claim that represents the resulting association between the asset and the video.
-
The
reference
resource's new
excludedIntervals[]
property specifies a list of time intervals during the reference that YouTube should ignore when trying to match the reference. Each interval specifies a start and end time measured in seconds from the start of the video.
-
The API no longer requires the
status
property to be set in the
reference
resource that is sent in the body of a
references.update
or
references.patch
request.
-
The documentation has been corrected to properly describe the API response format for the
videoAdvertisingOptions.getEnabledAds
method. The response, which is a
youtubePartner#videoAdvertisingOptionGetEnabledAds
resource, contains the following information:
-
id
– The ID that YouTube uses to uniquely identify the claimed video associated with the settings.
-
adBreaks
– A list of objects in which each object contains information about a point before, during, or after the video playback when ads are allowed to run. Each object may also specify other attributes of the ad break, such as the ad slots that occur during the break and the types of ads that are allowed to run during each slot.
-
adsOnEmbeds
– A boolean field that indicates whether YouTube can show ads when the video is played in an embedded player.
-
countriesRestriction
– A list of objects in which each object identifies a list of territories and the ad formats that are used during playbacks of the video in those territories.
-
New and updated errors
-
The table below identifies new errors that the API supports and the methods that could return each error. It also identifies errors that have changed. Note that a method may return multiple errors that have the same error type. For example, a
required
error is returned if you try to insert an
asset
resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.
Please refer to the error documentation for each method or to the
errors
page for more information.
Method
|
Errors
|
assets.insert
assets.update
assets.patch
|
invalidValue
and
required
errors previously associated with child properties of the
metadata
object are now associated with the same child properties in the
metadataMine
object.
|
claimHistory.get
|
notFound
– The claim for which you are trying to retrieve history cannot be found.
required
– The request does not specify a value for the
claimId
parameter.
|
claimSearch.list
claims.list
|
badRequest
– The request specifies invalid criteria. At most, one of the following filter parameters may be specified:
q
,
assetId
,
videoId
.
|
claims.insert
|
badRequest
– The claim you are trying to create is invalid because the requested content owner is not an owner of the asset associated with the claim.
badRequest
– The content owner that you are acting on behalf of does not have permission to create policies with the specified action.
invalidValue
– The content owner that you are acting on behalf of does not have permission to claim user-uploaded videos via the API.
|
contentOwners.list
|
badRequest
– The request specifies invalid criteria. Exactly one of the following filter parameters must be specified:
fetchMine
,
id
. (Previously, the error listed a different set of filter parameters –
has_conflicts_with
,
restrict_to_user
,
name_prefix
, and
id
.)
|
ownership.update
ownership.patch
|
badRequest
– A request that updates the ownership data of a composition asset must specify granular ownership data &ndahs;
mechanical
,
performance
,
synchronization
, and/or
lyric
rights – rather than
general
ownership rights. The
lyric
rights type is newly supported.
|
policies.insert
policies.update
policies.patch
|
invalidValue
– The request contains an invalid policy rule because the API does not support the creation or modification of policies that specify a
takedown
action. This error, which reports a reason of
invalidPolicyTakedownAction
, replaces the deprecated
invalidPolicyConditionalTakedown
error.
|
references.insert
|
badRequest
– The request must either send a media file or specify a value for the
claimId
request parameter. However, a request may not send a media file
and
specify a value for the
claimId
request parameter.
badRequest
– A reference for the same content has already been created from a different claim on the same YouTube video.
badRequest
– The API does not support the ability to set a value for the
fpDirect
property when creating a reference.
internalError
– There is a problem with the uploaded media file.
invalidValue
– The value of the
contentType
,
assetId
, or
claimId
request parameter is invalid. The error identifies the invalid value.
notFound
– The asset or claim that you specified cannot be found. Please check the
assetId
and
claimId
parameter values in your request.
required
– The request must specify a value for the
contentType
parameter.
|
references.insert
references.update
references.patch
|
invalidValue
– The
excludedIntervals
specified for the reference are not valid. Note that you cannot specify exclusion intervals when deactivating a reference.
|
May 10, 2013
This update contains the following changes:
April 8, 2013
This update contains the following changes:
-
The API has been renamed to the YouTube Content ID API.
-
Several properties have changed in the
assetMatchPolicy
resource:
- The
kind
property value has changed from
youtubePartner#policy
to
youtubePartner#assetMatchPolicy
.
- The new
policyId
property contains a value that uniquely identifies a
saved policy resource
.
- The
rules[].subaction
property value is now a list of strings rather than a string.
- The
rules[].conditions.contentMatchType
property value is now a list of strings rather than a string.
- The
id
,
name
, and
description
properties have been removed.
-
The documentation for the
assetMatchPolicy.update
method has been updated to reflect the fact that you can set values for either the
policyId
property or the
rules[]
object when calling the method.
-
The
claims
resource now supports several new properties:
Property name
|
Value
|
Description
|
timeCreated
|
datetime
|
The date and time that the claim was created.
|
matchInfo
|
object
|
The
matchInfo
object contains information about the matching content that generated the claim. This information is only included in a
claim
resource if the claim was automatically generated because an uploaded video matched an existing reference file.
|
matchInfo.
referenceId
|
string
|
The unique ID that YouTube uses to identify the reference
reference
that generated the match.
|
matchInfo.
longestMatch
|
object
|
The
longestMatch
object contains information about the longest match between the reference and the uploaded video.
|
matchInfo.longestMatch.
durationSecs
|
unsigned long
|
The duration of the match, in seconds.
|
matchInfo.longestMatch.
userVideoOffset
|
unsigned long
|
The time offset when the match begins, measured in seconds from the beginning of the uploaded video.
|
matchInfo.longestMatch.
referenceOffset
|
unsigned long
|
The time offset when the match begins, measured in seconds from the beginning of the reference.
|
matchInfo.
totalMatch
|
object
|
The
totalMatch
object contains information about the total amount of the uploaded video that matched the reference and about the total amount of the reference that matched the uploaded video. These values may differ if the matching content runs in a loop in either the uploaded video or the reference. For example, if an uploaded video includes a 10-second clip from a reference, but the clip is repeated six times, then the total matching content in the uploaded video is 60 seconds, but the total matching content in the reference is only 10 seconds.
|
matchInfo.totalMatch.
userVideoDurationSecs
|
unsigned long
|
The total length, in seconds, of the uploaded video's content that matches the reference.
|
matchInfo.totalMatch.
referenceDurationSecs
|
unsigned long
|
The total length, in seconds, of the reference content that matches the uploaded video.
|
origin
|
object
|
The
origin
object contains information that describes the source of the claim.
|
origin.
source
|
string
|
The source of the claim.
|
-
The
policy
property in the
claims
resource has been updated to note that the value cannot be updated for an AudioSwap claim.
-
The
metadataHistory
resource's
timeProvidedMs
property has been renamed to
timeProvided
.
-
The
ownershipHistory
resource's
timeProvidedMs
property has been renamed to
timeProvided
.
-
The definition of the
ownershipHistory.list
method has been updated to note that the method only retrieves the most recent ownership data for each content owner. However, if the content owner has submitted ownership data through multiple data sources (API, content feeds, etc.), the list will contain the most recent data for each content owner and data source.
-
Several properties have changed in the
policy
resource:
- The
rule
property has been renamed to
rules
.
- The
rules[].subaction
property value is now a list of strings rather than a string.
- The
rules[].conditions.contentMatchType
property value is now a list of strings rather than a string.
-
The documentation for the
policies.insert
and
policies.update
methods has been updated to reflect the fact that you can set values for the
rules[]
object when calling those methods.
-
Several API methods support new error types. The table below identifies the method and briefly identifies the types of newly supported errors. In many cases, there may be multiple errors for a given type. For example, a
required
error is returned if you try to insert an
asset
resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.
Please refer to the error documentation for each method or to the
errors
page for more information.
Method
|
Errors
|
assets.insert
|
invalidValue
– An asset metadata field contains an invalid value.
required
– A required asset metadata field is missing.
|
assets.update
assets.patch
|
forbidden
– The asset being updated is not owned by the partner attempting to complete the update.
invalidValue
– An asset metadata field contains an invalid value.
notFound
– The asset is being associated with a season asset or show asset that cannot be found.
required
– A required asset metadata field is missing.
|
claims.insert
|
badRequest
– The request attempts to claim a video, but the claim is not allowed.
|
ownership.update
ownership.patch
|
badRequest
– The request defines total ownership greater than 100 percent within a territory.
|
policies.insert
policies.patch
policies.update
|
conflictingPolicyRules
– The policy contains conflicting policy rules.
|
-
The new
errors
page lists errors that the API can return. The page includes general errors, which might occur for multiple different API methods, as well as method-specific errors.
January 18, 2013
This update contains the following changes:
-
The newly documented
videoAdvertisingOptions.getEnabledAds
method lets you retrieve details about the types of ads that are allowed for a specified partner- or user-uploaded video.
-
The definition of the
assetSearch.list
method's
ownershipRestriction
parameter has been updated to note that the default parameter value is
mine
, which indicates that the API should only retrieve assets owned by the current user.
-
The
assets.list
method's documentation reflects the following changes:
-
The
id
parameter is now required.
-
The newly supported
fetchMatchPolicy
parameter lets you indicate whether the API request should also retrieve the match policy that you have set for the asset.
-
The newly supported
fetchOwnership
parameter lets you indicate whether the API request should also retrieve ownership data for the asset.
-
The list of assets that the API returns no longer contains pagination data. As a result, the
nextPageToken
property and the
pageInfo
object have both been removed from the API response. The
pageInfo
object contained the
totalResults
,
resultsPerPage
, and
startIndex
properties.
-
The
claims
resource documentation has been updated to note that you must specify a policy when creating a claim. (YouTube does not currently apply your default usage policy if an inserted claim does not specify a policy, though the documentation previously indicated that that did happen.)
-
The
policy
resource's
hasUnpublishedDraft
property has been deprecated.
-
The
policies.list
method's newly supported
id
parameter lets you identify the saved policies that the API request should retrieve. Only policies belonging to the currently authenticated content owner can be retrieved.
-
The definition of the
releaseClaims
parameter for both the
references.patch
and
references.update
method has been updated to note that the parameter only works when the claim's status is being updated to
inactive
. In that case, you can also set the
releaseClaims
parameter's value to
true
to release all match claims produced by the reference.
-
The
references.patch
and
references.update
methods have both been updated to note that you must specify the reference's status when performing either of these operations.
-
Several API methods support new error types. The table below identifies the method and the newly supported errors:
Method
|
Error type
|
Error detail
|
Description
|
guideCategories.list
|
notFound
|
Unavailable
|
The asset for which you are trying to retrieve the match policy cannot be found.
|
claims.get
|
notFound
|
Unavailable
|
The claim that you are trying to retrieve cannot be found.
|
ownership.patch
|
invalidValue
|
Unavailable
|
The ownership data that you provided contains an invalid value.
|
ownership.update
|
invalidValue
|
Unavailable
|
The ownership data that you provided contains an invalid value.
|