From cdeb8027de15f0773adec153cc7ed92f64e98b9d Mon Sep 17 00:00:00 2001 From: Brian Colvin Date: Wed, 8 Jul 2026 11:43:50 -0700 Subject: [PATCH] Update search-feed.md Added live Signed-off-by: Brian Colvin --- docs/SPECIFICATIONS/search-feed.md | 531 ++++++++++------------------- 1 file changed, 189 insertions(+), 342 deletions(-) diff --git a/docs/SPECIFICATIONS/search-feed.md b/docs/SPECIFICATIONS/search-feed.md index a2857261..270c61f9 100644 --- a/docs/SPECIFICATIONS/search-feed.md +++ b/docs/SPECIFICATIONS/search-feed.md @@ -26,7 +26,7 @@ The Roku search feed includes the following key features: ### Root -The root of the JSON file contains basic information such as the Roku feed specification version, the default language, default availability for different regions, and the list of content items. +The root of the JSON file contains basic information such as the Roku feed specification version, the default language, default availability for different regions, and the list of content items. For live integrations see [Live feed specification](#live-feed-specification) below @@ -88,9 +88,15 @@ An asset represents a specific content item in the app's catalog. It contains al - + + + + + + + @@ -161,7 +167,7 @@ An asset represents a specific content item in the app's catalog. It contains al - + @@ -184,15 +190,33 @@ An asset represents a specific content item in the app's catalog. It contains al - + - + + + + + + + + + + + + + + + + + + +
type EnumThe media type of the content item:
  • movie: Movie or long-form film (over 15 minutes).
  • tvspecial: One-time TV program that is not part of a series, or content that does not fit into any other mediaType category (for example, music, artists, sporting events, non-episodic news specials).
  • series: Set of related serialized episodes and possibly seasons. Includes TV shows and daily/weekly ongoing shows.
  • season: As part of a series, single set of related TV episodes.
  • episode: Single content item (an episode of a TV show, for example).
  • shortform: Standalone content that is 15 minutes or less that is not a movie or TV show (for example, movie trailers, news clips, comedy clips, food reviews, or other clips).
  • externalIdOnly: Validates the id, externalIdSource, and playOptions fields only. For a linear feed, validates the id and externalIdSource fields only.

This value is passed into [deep links](doc:implementing-deep-linking#mediatype-behavior) that are sent to the app. The app uses the value to determine how to launch the content. For example, if the type is "movie", the app will launch it directly into playback.		The media type of the content item:
  • movie: Movie or long-form film (over 15 minutes).
  • tvspecial: One-time TV program that is not part of a series, or content that does not fit into any other mediaType category (for example, music, artists, sporting events, non-episodic news specials).
  • series: Set of related serialized episodes and possibly seasons. Includes TV shows and daily/weekly ongoing shows.
  • season: As part of a series, single set of related TV episodes.
  • episode: Single content item (an episode of a TV show, for example).
  • shortform: Standalone content that is 15 minutes or less that is not a movie or TV show (for example, movie trailers, news clips, comedy clips, food reviews, or other clips).
  • liveStream: a live channel. In this integration, however, the "liveStream" type specified in the feed is sent as a "livefeed" mediaType in deep link requests.
  • externalIdOnly: Validates the id, externalIdSource, and playOptions fields only. For a linear feed, validates the id and externalIdSource fields only.

This value is passed into [deep links](doc:implementing-deep-linking#mediatype-behavior) that are sent to the app. The app uses the value to determine how to launch the content. For example, if the type is "movie", the app will launch it directly into playback.		 Required
subTypeEnumThe subType of the content item:
  • teaser
  • trailer
  • highlight
  • making_of
  • behind_scenes
  • interview
  • related
  • recap
  • extra
  • short
  • ancillary

This value is used to provide more detail on the type of shoulder content.		Optional
externalIds ExternalId\[]images Image\[] A list of main poster and background images to be displayed for the content item in the Roku Search results.

Images may have an aspect ratio of 16:9 or 2:3.

Roku determines the dimensions and aspect ratio to be used after downloading the image.		A main 16:9 or 2:3 poster image is required.A main 16:9 or 2:3 poster image is required. Unless the type is "episode", in which case only a background is needed
content
episodeInfo EpisodeInfoMetadata related to a television episode.
The EpisodeInfo object specifies the episode number, season number, and series ID of the episode.		Metadata related to a television episode.
The EpisodeInfo object specifies the episode number, season number, and series ID of the episode.		 Required only if the type field is "episode".
seasonInfo SeasonInfoMetadata related to a television season.

The SeasonInfo object specifies the season number and series ID of the season.		Metadata related to a television season.

The SeasonInfo object specifies the season number and series ID of the season.		 Required only if the type field is "season".
liveInfoLiveInfoMetadata related to live events.

The LiveInfo object specifies the start and end time of a live event.		Required only if a PlayOption is marked as live.
stationInfoStationInfoA reference to a Gracenote Source prgSvcId for a "liveStream" schedule.

The StationInfo object specifies the Gracenote Station Schedule identifier.		Required only if the type field is "liveStream".
relationshipsRelationship\[]A list of related content to this program.

Relations may reference TMS ids or REF ids (other content in your catalog)		Optional
@@ -277,7 +301,7 @@ Provide the names and roles of cast and crew members that may receive credit for role String - The role of the person: + The role of the person: Required @@ -335,9 +359,21 @@ For each country supported by Roku Search, the rating authorities, ratings, and au ACB (Australian Classification Board) - + + + at + ABMC (Austrian Board of Media Classification) + + + + + gb + BBFC (British Board of Film Classification) + + + br CLASSIND (Classificação Indicativa) @@ -368,12 +404,6 @@ For each country supported by Roku Search, the rating authorities, ratings, and - - gb - BBFC (British Board of Film Classification) - - - mx RTC (General Directorate of Radio Television and Cinematography) @@ -400,7 +430,7 @@ For each country supported by Roku Search, the rating authorities, ratings, and Provide the poster and background images to be displayed for the content item in the Roku Search results. Provide localized images for each region in which the item is to be made available to Roku Search. The supported image formats and aspect ratios are as follows: * **format**: JPEG (.jpg file extension), GIF (.gif file extension) or PNG (.png file extension) -* **aspect ratio**: 16:9 or 2:3 required. +* **aspect ratio**: 16:9 or 2:3 required, but 4:3, 3:4, 1:1 are also supported * **maximum resolution**: 1920 X 1080 @@ -416,7 +446,7 @@ Provide the poster and background images to be displayed for the content item in - + @@ -438,84 +468,28 @@ Provide the poster and background images to be displayed for the content item in | Field | Type | Description | Required | | :---------- | :------------- | :------------------------------------------------ | :------- | -| playOptions | [PlayOption](#playoption) | The list of options for playing the content item. | Required | +| playOptions | [PlayOption](#playoptions) | The list of options for playing the content item. | Required | #### playOptions In the **playOptions** field, specify the availability, pricing, licensing, quality, and playId (for [deep linking](doc:implementing-deep-linking) into content from Roku Search) for the content item. -
type EnumThe image type:
  • main: A poster image with title treatment. The aspect ratio of the poster may be 16:9 or 2:3.
  • background: A textless image displayed in the background. The aspect ratio of the background image may be 16:9 or 2:3.
The image type:
  • main: A poster image with title treatment. The aspect ratio of the poster may be 16:9 or 2:3. Can also be sent as "poster"
  • background: A textless image displayed in the background. The aspect ratio of the background image may be 16:9 or 2:3.
  • logo
 Required
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescriptionRequired
licenseEnumThe type of licensing terms for the content:
  • free: Content is directly playable upon being deep linked.
  • subscription: Content is only playable upon being deep linked if the customer has a subscription. For customers that do not have a subscription, the app typically displays a subscription sign-up page when receiving deep links into content that is behind a paywall.
  • rental
  • purchase
Required
priceFloatThe price of the content in decimal format (for example, 1.90, 1.99, or 2.00).

If the price is 0.00, set the license field to "subscription" or "free" instead of setting this field. This automatically sets the price field to 0.00 by default.		Required, if the license field is set to "purchase" or "rental".
qualityEnumThe playback resolution of the content item:
  • sd
  • hd
  • hd+
  • fhd
  • uhd
Required
currencyStringThe ISO 4217 three-letter currency code for the value specified in the price field:
  • usd (or USD) (default)
  • gbp (or GBP)
  • cad (or CAD)
  • eur (or EUR)
Required, if the license field is set to "purchase" or "rental".
playIdStringA unique, immutable ID for the content item. When customers search for this content item and select your app to watch it, the playId is passed in a [deep link](doc:implementing-deep-linking) back to your app.

The playId must map to the contentid in your app for the same content. It is therefore important to keep the Roku Search feed synchronized with the app's content feed.		Required
availabilityStartTimeStampNumberThe time (in epoch milliseconds) when the content item is to be made available to Roku Search.Optional

If you are not providing an availability start time, omit this field from your search feed.
availabilityEndTimeStampNumberThe time (in epoch milliseconds) when the content item is to stop being made available to Roku Search.Optional

If you are not providing an availability end time or if the content is available indefinitely, omit this field from your search feed.
availabilityStartTimeStringThe time (as an ISO timestamp) when the content item is to be made available to Roku Search.Optional

If you are not providing an availability start time, omit this field from your search feed.
availabilityEndTimeStringThe time (as an ISO timestamp) when the content item is to stop being made available to Roku Search.Optional

If you are not providing an availability end time or if the content is available indefinitely, omit this field from your search feed.
availabilityInfoMap\The list of ISO Alpha-2 two-letter country codes in which the content item is to be made available to Roku Search.Required, if the defaultAvailabilityCountries field is not specified.
+| Field | Type | Description | Required | +| :----------- | :----- | :---------------------------------------- | :------- | +| license | Enum | The type of licensing terms for the content: | Required | +| price | Float | The price of the content in decimal format (for example, 1.90, 1.99, or 2.00).

If the price is 0.00, set the **license** field to "subscription" or "free" instead of setting this field. This automatically sets the **price** field to 0.00 by default. | Required, if the **license** field is set to "purchase" or "rental". | +| quality | Enum | The playback resolution of the content item: | Required | +| currency | String | The [ISO 4217 three-letter currency code](https://www.iso.org/iso-4217-currency-codes.html) for the value specified in the **price** field: | Required, if the **license** field is set to "purchase" or "rental". | +| playId | String | A unique, immutable ID for the content item. When customers search for this content item and select your app to watch it, the **playId** is passed in a [deep link](doc:implementing-deep-linking) back to your app.

The **playId** must map to the **contentid** in your app for the same content. It is therefore important to keep the Roku Search feed synchronized with the app's content feed. | Required | +| availabilityStartTimeStamp | Number | The time (in epoch milliseconds) when the content item is to be made available to Roku Search. | Optional

If you are not providing an availability start time, omit this field from your search feed. | +| availabilityEndTimeStamp | Number | The time (in epoch milliseconds) when the content item is to stop being made available to Roku Search. | Optional

If you are not providing an availability end time or if the content is available indefinitely, omit this field from your search feed. | +| availabilityStartTime | String | The time (as an ISO timestamp) when the content item is to be made available to Roku Search. | Optional

If you are not providing an availability start time, omit this field from your search feed. | +| availabilityEndTime | String | The time (as an ISO timestamp) when the content item is to stop being made available to Roku Search. | Optional

If you are not providing an availability end time or if the content is available indefinitely, omit this field from your search feed. | +| live | boolean | Used to indicate the watch option is live content. This is a short hand for "discreteLiveEvent", if set, the values in the "liveInfo" will be used. | Optional | +| discreteLiveEvent | [LiveEvent](#liveevent) | The timing in which the watch option is "live" may be different than [LiveInfo](#liveinfo) in case of pre and postgame shows | Optional | +| promotionalStartTime | String | The time (as an ISO timestamp) when the content item might be promoted as coming soon to Roku Search. | Optional | +| promotionalEndTime | String | The time (as an ISO timestamp) when the content item is no longer promoted. The default is the availability start | Optional | +| availabilityInfo | [AvailabilityInfo](#availabilityinfo) | May include following: | Required, if the **defaultAvailabilityCountries** field is not specified. | ### SeasonInfo @@ -536,195 +510,155 @@ If the **asset.type** field is set to "episode" for a content item, provide meta | seasonNumber | Number | The season number in which the episode occurs. | Optional | | episodeNumber | Number | The number used to identify the episode within the season. | Required | -### ExternalId +### LiveInfo -Provide a list of IDs and sources to be used for linking external metadata to the content item. +If the program is a "live" event this field indicates when the actual event is occuring. - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescriptionRequired
idStringThe third-party metadata provider ID that uniquely identifies the content item.

For Gracenote/TMS, the ID is a 14-character string (for example, MV123456780000). The first 2 characters in the ID represent the unique ID domain applied to the program record:
  • MV: Movie (theatrical, made-for-television, direct-to-video).
  • EP: Television episode.
  • SH: Television show
Required
sourceStringThe source of the specified external ID. This must be one of the following values:
  • TMS
Required
- -
- -## Live feed specification - -Apps in the U.S. Streaming Store with 24/7 live linear streams can participate in Roku's Live Search by creating and submitting a web-hosted JSON feed that includes the 24/7 live channels in their service. The Roku Live Search feed is modeled after Roku's Search feed JSON specification above, but requires only a small subset of fields. One of the fields is the **externalIds** field, which contains the Gracenote station IDs for the live channels to be discoverable. - -Your search feed may only include channels directly distributed by your app. Do not include channels offered through third-party channel subscriptions (subscriptions or add-ons that require a separate publisher account). +| Field | Type | Description | Required | +| :------------ | :----- | :--------------------------------------------------------- | :------- | +| startTimeStamp| Number | Start time in milliseconds of the live event | Required | +| endTimeStamp | Number | End time in milliseconds of the live event | Required | -> The live liner integration requires Gracenote Station IDs. Individual live events or channels without Gracenote Station IDs are currently not supported. Roku uses Gracenote EPG and GSD data (schedule of event IDs). Publishers are responsiiblwe for contacting Gracenote to get their Station IDs. +### LiveEvent -### Specifications +If the playOption is "live" event this field indicates when the stream should go live. -#### Root +| Field | Type | Description | Required | +| :------------ | :----- | :--------------------------------------------------------- | :------- | +| streamStart | Number | Start time in milliseconds of the live stream | Required | +| eventStart | Number | Start time in milliseconds of the event | Required | +| eventEnd | Number | End time in milliseconds of the event | Required | +| streamEnd | Number | End time in milliseconds of the live stream | Required | -The root of the JSON file contains basic information such as the feed specification version, the default language, default availability for different regions, and the list of live channels. +### StationInfo -| **Field** | **Type** | **Description** | **Required/Optional** | -| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | -| version | String | Roku JSON feed version (use "1"). | Required | -| defaultLanguage | String | The [ISO 639-1 two-letter language code](https://www.loc.gov/standards/iso639-2/php/code_list.php) to be used when the language is not specified for an asset. | Required (if you do not provide the language for each asset). | -| defaultAvailabilityCountries | String[] | The list of [ISO Alpha-2 two-letter country codes](https://www.iso.org/obp/ui/#search) to be used when **availabilityInfo.country** is not specified for an asset. | Required (if you do not provide the availability countries for each asset). | -| assets | [Asset](https://roku.atlassian.net/wiki/spaces/NPIPM/pages/450330792/Live+Search+feed+requirements#Asset)[] | The list of live channels in the distributor's service to be surfaced in Roku's Search. | Required | +If the **asset.type** field is set to "liveStream" for a content item, provide metadata about the channel. The Gracenote tech ID (prgSvcId) for the live channel to be made discoverable through the Roku Search customer experience. -#### Asset +| Field | Type | Description | Required | +| :------------ | :----- | :--------------------------------------------------------- | :------- | +| stationId | String | The Gracenote prgSvcId of the Source station | Required | +| callSign | String | Optional callsign information | Optional | +| dma | Number | Optional dma information | Optional | -An asset represents a specific live channel in the distributor's service. It contains all the metadata for displaying the live channel in the Roku Search UI and directly launching the channel via deeplinking when selected. +### ExternalId -| **Field** | **Type** | **Description** | **Required/Optional** | -| ----------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| id | String | A maximum 50-character immutable unique ID for the live channel. This ID is used by the distributor for reference.Once an ID is created for a channel, it may not be changed. The id must be unique within the feed. If the feed contains duplicate IDs, only one of the items with the duplicated ID is preserved. | Required | -| type | Enum | The media type of the live channel, which is **liveStream**. Channels use the type to determine how to launch content.Typically, the type specified in the search feed is directly passed into deep link requests to channels. In this integration, however, the "liveStream" type specified in the feed is sent as a "livefeed" mediaType in deep link requests. Channels participating in Roku's Live Search Feed must therefore launch the channel specified in the **playId** field directly into playback upon receiving a deep link request with the mediaType set to "livefeed". | Required | -| externalIds | [ExternalId](https://roku.atlassian.net/wiki/spaces/NPIPM/pages/450330792/Live+Search+feed+requirements#ExternalId)[] | The list of Gracenote tech IDs (prgSvcID) for the live channels to be discoverable through the Roku Search customer experience. Roku uses Gracenote stationIDs to obtain EPG and GSD data. Partners need to contact Gracenote directly to obtain stationIDs for their livelinear channels. | Required | -| content | [Content](https://roku.atlassian.net/wiki/spaces/NPIPM/pages/450330792/Live+Search+feed+requirements#Content) | Contains options for playing the live channel. The Content object includes a **playOptions** field that specifies the availability, pricing, licensing, quality, and playId (for deep linking into content from Roku Search) for the live channel. | Required | -| tags | String[] | A list of one or more distributor-specific strings for categorizing the channel. | Optional | +Provide a list of IDs and sources to be used for linking external metadata to the content item. -#### ExternalId +| Field | Type | Description | Required | +| :------------ | :----- | :--------------------------------------------------------- | :------- | +| id | String | The third-party metadata provider ID that uniquely identifies the content item.

For Gracenote/TMS, the ID is a 14-character string (for example, MV123456780000). The first 2 characters in the ID represent the unique ID domain applied to the program record: