String - required

Document title from your database. A UTF-8 encoded string. Limited to 1000 characters.

String - required

Document categories. This property is repeated for supporting one document belonging to several parallel categories. Use the full category path for higher quality results.

To represent the full path of a category, use the> symbol to separate hierarchies. If> is part of the category name, replace it with another character(s).

For example:

"categories": [ "sports > highlight" ]

A document can contain at most 250 categories. Each category is a UTF-8 encoded string with a length limit of 5000 characters.

String - required

URI of the document. Length limit of 5000 characters.

String - highly recommended

Description of the document. Length limit of 5000 characters.

String - this field is required for movies and shows

Top-level category.

Supported types:movie,show,concert,event,live-event,broadcast,tv-series,episode,video-game,clip,vlog,audio,audio-book,music,album,articles,news,radio,podcast,book, andsports-game.

The valuesmovie andshow have special significance. They cause documents to be enriched in a way that improves ranking and helps users making title searches to find alternate content they might be interested in.

String - optional

Language of the title/description and other string attributes. Use language tags defined byBCP 47.

For document search this field is in use. It defaults toen-US if unset. For example,"language_code": "en-US".

For media, such as movies, that have metadata in multiple languages, treat each language version as a separate document; each version has its own title, description, categories, and other property fields in the corresponding language. To distinguish between different language versions, use thelanguage_code property. This property also lets you filter search results on the serving side, so that only media content in the relevant language is returned for a query.

String - required for media recommendations apps where the business objective is click-through rate (CVR) or watch duration per session.

Duration of the media content. Duration should be encoded as a string. Encoding should be the same as thegoogle::protobuf::Duration JSON string encoding. For example: "5s", "1m"

Datetime - required

The time that the content is available to the end-users. This field identifies the freshness of a content for end-users. The timestamp should conform to RFC 3339 standard.

For example:

"2022-08-26T23:00:17Z"

To filter on availability, seeFilter recommendations andFilter for available documents.

Datetime - optional

The time that the content will expire for the end-users. This field identifies the freshness of a content for end-users. The timestamp should conform to RFC 3339 standard.

For example:

"2032-12-31T23:00:17Z"

To exclude expired documents from results, seeFilter recommendations andFilter media search.

Datetime - optional

The time that the live event begins. The timestamp should conform to RFC 3339 standard.

For example:

"2020-12-31T23:00:17Z"

Datetime - optional

The time that the live event is finished. The timestamp should conform to RFC 3339 standard.

For example:

"2024-01-28T23:00:17Z"

String - optional - repeated

Language of the media contents. Use language tags defined byBCP 47.

For example:"in_languages": [ "en-US"]

String - optional

Media document country of origin. Length limit of 128 characters.

For example:"country_of_origin": "US"

String - optional

Transcript of the media document.

Integer - optional

Content index of the media document. Content index field can be used to order the documents relative to others. For example, episode number can be used as the content index.

Content index should be a non-negative integer.

For example:"content_index": 0

String - optional - repeated

Filter tags for the document. At most 250 values are allowed per document with a length limit of 1000 characters. Otherwise, an INVALID_ARGUMENT error is returned.

These tags can be used to filter search results and recommendations results. To filter recommendations results, pass the tags as part of theRecommendRequest.filter. The tags are only used to filter returned results; the values of the tags don't affect the results that are returned by the search and recommendations models.

For example:"filter_tags": [ "grade_level", "season"]

String - optional - repeated

Hashtags for the document. At most 100 values are allowed per document, with a length limit of 5000 characters.

For example:"hash_tags": [ "soccer", "world cup"]

Integer - optional

The year the media was produced.

String - optional - repeated

The content rating, used for content advisory systems and content filtering based on the audience. At most 100 values are allowed per document with a length limit of 128 characters.

This tag can be used to filter recommendations results by passing the tag as part of theRecommendRequest.filter.

For example:content_rating: ["PG-13"]

Object - optional - repeated

Root key property for encapsulating image-related properties.

String - optional

URI of the image. Length limit of 5,000 characters.

String - optional

Name of the image. Length limit of 128 characters.

Object - optional - repeated

Root key property for encapsulating the person-related properties.

For example:"persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]

String - required

Name of the person.

String - required

The role of the person in the media item.

Supported values: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role

If none of the supported values are applied torole, setrole tocustom-role and provide the value in thecustom_role field.

String - optional

custom_role is set if and only if therole is set to be acustom-role. Must be a UTF-8 encoded string with a length limit of 128 characters. Must match the pattern:[a-zA-Z0-9][a-zA-Z0-9_]*.

Integer - optional

Used for role ranking. For example, for first actor,role = "actor", rank = 1

String - optional

URI of the person.

Object - optional - repeated

Root key property for encapsulating theorganization-related properties.

For example:"organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]

String - required

Name of the organization.

String - required

The role of the organization in the media item.

Supported values: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role

If none of the supported values are applied torole, setrole tocustom-role and provide the value in thecustom_role field.

String - optional

custom_role is set if and only if therole is set to be acustom-role. Must be a UTF-8 encoded string with a length limit of 128 characters. Must match the pattern:[a-zA-Z0-9][a-zA-Z0-9_]*.

String - optional

Used for role ranking. For example, for first publisher:role = "publisher", rank = 1

String - optional

URI of the organization.

Object - optional - repeated

Root key property for encapsulating theaggregate_rating related properties.

String - required

The source for rating. For example,imdb orrotten_tomatoes. Must be a UTF-8 encoded string with a length limit of 128 characters. Must match the pattern:[a-zA-Z0-9][a-zA-Z0-9_]*.

Double - required

The aggregated rating. The rating should be normalized to the [1, 5] range.

Integer - optional

The number of individual reviews. Should be a non-negative value.

String - required

Document title from your database. A UTF-8 encoded string. Limited to 1000 characters.

String - required

URI of the document. Length limit of 5000 characters.

String - required

Document categories. This property is repeated for supporting one document belonging to several parallel categories. Use the full category path for higher quality results.

To represent the full path of a category, use the> symbol to separate hierarchies. If> is part of the category name, replace it with another character(s).

For example:

"categories": [ "sports > highlight" ]

A document can contain at most 250 categories. Each category is a UTF-8 encoded string with a length limit of 5000 characters.

Datetime - required

The time that the content is available to the end-users. This field identifies the freshness of a content for end-users. The timestamp should conform to RFC 3339 standard.

For example:

"2022-08-26T23:00:17Z"

To filter on availability, seeFilter recommendations andFilter for available documents.

String - required for media recommendations apps where the business objective is click-through rate (CVR) or watch duration per session.

Duration of the media content. Duration should be encoded as a string. Encoding should be the same as thegoogle::protobuf::Duration JSON string encoding. For example: "5s", "1m"

This field is important for media recommendations apps where the business objective is to maximize the conversion rate (CVR) or the watch duration per visitor.

String - highly recommended

Description of the document. Length limit of 5000 characters.

Object - optional - repeated

Root key property for encapsulating image-related properties.

String - optional

Name of the image. Length limit of 128 characters.

String - optional

URI of the image. Length limit of 5,000 characters.

String - optional

Language of the title/description and other string attributes. Use language tags defined byBCP 47.

For document recommendations, this field is ignored and the text language is detected automatically. The document can include text in different languages, but duplicating documents to provide text in multiple languages can result in degraded performance.

For document search this field is in use. It defaults toen-US if unset. For example,"language_code": "en-US"

For media, such as movies, that have metadata in multiple languages, treat each language version as a separate document; each version has its own title, description, categories, and other property fields in the corresponding language. To distinguish between different language versions, use thelanguage_code property. This property also lets you filter search results on the serving side, so that only media content in the relevant language is returned for a query.

Object - optional - repeated

Root key property for encapsulating theaggregate_rating related properties.

Integer - optional

The number of individual reviews. Should be a non-negative value.

Double - required

The aggregated rating. The rating should be normalized to the [1, 5] range.

String - required

The source for rating. For example,imdb orrotten_tomatoes. Must be a UTF-8 encoded string with a length limit of 128 characters. Must match the pattern:[a-zA-Z0-9][a-zA-Z0-9_]*.

Integer - optional

Content index of the media document. Content index field can be used to order the documents relative to others. For example, episode number can be used as the content index.

Content index should be a non-negative integer.

For example:"content_index": 0

String - optional - repeated

The content rating, used for content advisory systems and content filtering based on the audience. At most 100 values are allowed per document with a length limit of 128 characters.

This tag can be used to filter recommendations results by passing the tag as part of theRecommendRequest.filter.

For example:content_rating: ["PG-13"]

String - optional

Media document country of origin. Length limit of 128 characters.

For example:"country_of_origin": "US"

Datetime - optional

The time that the content will expire for the end-users. This field identifies the freshness of a content for end-users. The timestamp should conform to RFC 3339 standard.

For example:

"2032-12-31T23:00:17Z"

To exclude expired documents from results, seeFilter recommendations andFilter media search.

Datetime - optional

The time that the live event begins. The timestamp should conform to RFC 3339 standard.

For example:

"2020-12-31T23:00:17Z"

Datetime - optional

The time that the live event is finished. The timestamp should conform to RFC 3339 standard.

For example:

"2024-01-28T23:00:17Z"

String - optional - repeated

Filter tags for the document. At most 250 values are allowed per document with a length limit of 1000 characters. Otherwise, an INVALID_ARGUMENT error is returned.

This tag can be used to filter recommendations results by passing the tag as part of theRecommendRequest.filter.

For example:"filter_tags": [ "filter_tag"]

String - optional - repeated

Hashtags for the document. At most 100 values are allowed per document, with a length limit of 5000 characters.

For example:"hash_tags": [ "soccer", "world cup"]

String - optional - repeated

Language of the media contents. Use language tags defined byBCP 47.

For example:"in_languages": [ "en-US"]

Object - optional - repeated

Root key property for encapsulating theorganization-related properties.

For example:"organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]

String - optional

custom_role is set if and only if therole is set to be acustom-role. Must be a UTF-8 encoded string with a length limit of 128 characters. Must match the pattern:[a-zA-Z0-9][a-zA-Z0-9_]*.

String - required

Name of the organization.

String - optional

Used for role ranking. For example, for first publisher:role = "publisher", rank = 1.

String - required

The role of the organization in the media item.

Supported values: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role

If none of the supported values are applied torole, setrole tocustom-role and provide the value in thecustom_role field.

String - optional

URI of the organization.

Object - optional - repeated

Root key property for encapsulating the person-related properties.

For example:"persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]

String - optional

custom_role is set if and only if therole is set to be acustom-role. Must be a UTF-8 encoded string with a length limit of 128 characters. Must match the pattern:[a-zA-Z0-9][a-zA-Z0-9_]*.

String - required

Name of the person.

Integer - optional

Used for role ranking. For example, for first actor,role = "actor", rank = 1

String - required

The role of the person in the media item.

Supported values: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role

If none of the supported values are applied torole, setrole tocustom-role and provide the value in thecustom_role field.

String - optional

URI of the person.

Integer - optional

The year the media was produced.

String - optional

Transcript of the media document.

String - this field is required for movies and shows

Top-level category.

Supported types:movie,show,concert,event,live-event,broadcast,tv-series,episode,video-game,clip,vlog,audio,audio-book,music,album,articles,news,radio,podcast,book, andsports-game.

The valuesmovie andshow have special significance. They cause documents to be enriched in a way that improves ranking and helps users making title searches to find alternate content they might be interested in.