How to Make a Roku Search Feed


Important! In order to make a Roku Search Feed you must have a Commercial Custom SDK channel that has been published as a PUBLIC channel. Roku will not accept Search Feed requests using the procedure described below for channels that are not already PUBLIC and in the on-screen Channel Store. Free and Unlimited Custom SDK Channels do not support Roku Search. Roku Search Feeds for Direct Publisher channels cannot be configured within Instant TV Channel.

For information about creating a stand-alone Roku Search Feed WITHOUT using Instant TV Channel to manage your SDK channel, click here.

What is Roku Search?

Roku Search is located on the main menu of the Roku home-screen, and allows Roku users to search for a particular movie, TV show/special, or actor/actress/director. Roku Search then allows users to see a list of providers, choose a provider's channel to launch, and go directly to the selected piece of content.

Roku Search is only available in English and Spanish, and only available in the U.S., Canada (English only), Ireland, the U.K, and Latin-America countries. Roku Search only supports full-length movies and TV series, episodes, and specials. Roku Search does not support short-form or clip content.

A Roku Search Feed is the way in which you provide Roku with information about what video content is in your channel, so that it can be included in the Roku Search results. When your channel has a Roku Search Feed, all Roku users in the countries or regions that you specify will be able to find content in your channel, and will be able to quickly install your channel if it is not already installed.


Roku Search Keyboard


Result Selected from Roku Search Keyboard


Channel List for Selected Result - With 143w x 112h Teaser Logos


Channel List for Selected Result - With 165w x 60h Small Logos

Various Roku firmware versions may display the search results slightly differently. The channel poster artwork in the results is provided by the channel developer (you). Roku currently requires that two separate channel logo sizes are provided, a 143x112 "Teaser Logo" and a 165x60 "Small Logo".


Adding Video Items to a Roku Search Feed

The following steps will add a video item to a Roku Search Feed by matching the video item to an entry in the Gracenote TMS database.

  1. Starting on the Content page, verify that the Title parameter for the video item contains the correct spelling of the title. The spelling must be correct, including special characters such as punctuation marks, or a match may not be found. If in doubt, check the spelling of the video item in an online database such as IMDB.

    If the video is an Episode, you must provide a Series Title in the TitleSeries parameter box before a match can be found.

    Both the Title and TitleSeries parameters can be changed after a Gracenote match has been selected without affecting the Search Feed.

    The following example screens will match the "Plan 9 From Outer Space" movie to the corresponding entry in the Gracenote TMS database.


Roku Search Button - Before Clicking
  1. Click the Roku Search button. The Title parameter will be temporarily replaced with instructions.


Roku Search Button - Clicked
  1. After clicking the button, examine each item in the list of possible matches and select the correct item from the Gracenote TMS database.

Roku Search Button - Possible Matches Displayed
  1. If your video is not in the list, click the Roku Search button again to restore the original title, then try again after correcting your movie or TV show title.

    Do not select an item which is not a valid match. Doing so will result in an incorrect Search Feed and may result in Roku removing your channel from Roku Search.

    It's OK if some of the video items in your channel cannot be matched. These items will not be included in the Search Feed.

  2. When a match has been selected the Roku Search button changes color to green, and "(OFF)" changes to "(ON)", and a search icon - a magnifying glass - will appear next to the video item in the content tree.

Roku Search Button - Match Selected


Matched Content Item in Content Tree
  1. The Roku Search button can be clicked again to change or verify the selected match, or to turn off Roku Search for this video item. The last entry in the list of possible matches is NONE which if selected will turn off Roku Search for the video item.
  2. Repeat the above steps for each video item in the channel that should be added to the Roku Search Feed.

Obtaining the Roku Search Feed URL

The Roku Search Feed is generated "on-the-fly" whenever Roku requests it, so it is not necessary to generate, re-generate, or refresh the Search Feed. All that is necessary is to obtain the Search Feed's URL so that it can be provided to Roku.

  1. On the "Channels" page observe that there is a "Search" column with a magnifying-glass icon for each Commercial channel. Superimposed on the magnifying-glass icon is a 3-digit Roku Search ID number.

    The Roku Search ID numbers should be unique within each Instant TV Channel account, although multiple older Commercial channels may have a temporary ID of "000". Any channel that will be used with Roku Search must have a unique Roku Search ID, otherwise feed information for the wrong channel may be incorrectly provided to Roku.


Channel with Search ID of 000
    

Channel with Search ID of 123
  1. Click the magnifying-glass icon for the channel that will be used with Roku Search.
  2. If necessary, change the Roku Search ID to a unique value and click the Update Search ID button. For example if the Roku Search ID is "000", change it to any other unique 3-digit value.

    The value of the Search ID can be set to any unique 3-digit number. If the Search ID is not unique then a warning message will be displayed.

  3. The Roku Search Feed URL is displayed at the top of the page. Save this URL, it will be needed for a later step. The URL is password-protected and is not viewable.

Roku Search Feed URL for ID 123

Email Search Feed Information to Roku

An email must be sent to to complete the processing of the Search Feed.

The email should be sent from the login email address associated with your Roku Developer Account.

The subject line of the email must be ITVC Search Feed Submission for: My Channel, with My Channel replaced with the name of the public channel that the Search Feed is for.

The message body of the email must contain the following information:

  1. The access code for a private non-certified version of the channel for Roku to use for testing.
    • The private non-certified version of the channel should be made with the same Pkg file used for the public version of the channel.
    • A private non-certified version of the channel can be created the same way as the original public version was created, except select "Private" or "Non-Certified" at the first step of creating the channel in your Roku Developer Account.
    • The name of the private channel must have Search Beta appended to the name of the public channel. For example if the public channel's name is A Really Good Channel then the private non-certified version must be named A Really Good ChannelSearch Beta. Note that there is no space before "Search".
  2. The access code for the public version of the channel. Important: Before submitting a Search Feed request to Roku, the channel MUST have already been published as a PUBLIC channel and be present on the on-screen Channel Store. Roku will not approve Search Feeds using this procedure for channels that have not already been approved as a PUBLIC channel.
  3. The Search Feed URL that you previously saved.
  4. A 143w X 113h "Teaser Logo".
    • The image format must be PNG.
    • The image must be similar in appearance (other than size) to the 540x405 Channel Store icon.
    • Corners must be square.
    • Use an inner shadow effect for the teaser logo to conform to the default Scene Graph list item focus appearance.
    • If a gradient is applied to the artwork, use a gradient with the light source at the top of the artwork.

143x113 Teaser Logo
  1. A 165w X 60h "Small Logo".
    • The image format must be PNG.
    • The image must be similar in appearance (other than size) to the 540x405 Channel Store icon.
    • Corners must be rounded.
    • If a gradient is applied to the artwork, use a gradient with the light source at the top of the artwork.

165x60 Small Logo

Use this as a template for the email sent to :

Subject: ITVC TMS Search Feed Submission for:

Private Channel Access Code:

Public Channel Access Code:

TMS Search Feed URL:

143x113 Teaser Logo and 165x60 Small Logo are attached.

The Partner Success team at Roku will usually respond to the email within a few business days.


Other Search Feed Parameters

The following parameters are available on both the Theme page and on the Content page in individual video items. If the video item parameter on the Content page is set to "Theme" or is blank, then the Theme page parameter will be used, otherwise the video item parameter on the Content page takes precendence over the Theme page parameter. Each video item can have multiple sets of parameters, one set for each available Roku Search region. These parameters will need to be configured if the channel uses "In-Channel Purchasing".

  • RokuSearchCurrency - The currency used if purchasing videos. This parameter selects the currency symbol displayed in the on-screen Roku Search results, but it does not determine the actual currency type charged for the video.
  • RokuSearchLicense - The Payment method used if purchasing videos. This selection is displayed in the on-screen Roku Search results, but it does not determine the actual payment method for the video.
  • RokuSearchPrice - The price that is charged for each video. This price is displayed in the on-screen Roku Search results, but it does not determine the actual amount charged for the video.
  • RokuSearchQuality - The quality of the videos. This parameter selects the symbol displayed in the on-screen Roku Search results, but it does not determine the actual video playback quality.
  • RokuSearchRegion - This parameter determines the region in which videos will be visible for Roku Search. It only affects visibility within the Roku Search results, it does not affect the visibility of the video within the channel. The default setting is "All" which causes the channel to be visible in all available Roku Search regions.

    If any of the Roku Search parameters vary on a per-region basis, then regions and associated settings must be configured separately within each video item on the Content page.

The following parameter is available on the Theme page. This parameter may need to be configured if the channel uses a language other than English.

  • RokuSearchDescription - This parameter filters the possible Gracenote matches by the description language, and will cause the on-screen Roku Search description for matched item to be displayed in the selected language. This parameter only affects NEW matched items, it has no effect on already-matched items. The default setting is "en" (English).

The following parameters are available on the Account page. Usually these parameters will not need to be changed.

  • Show Roku Search Adult Content - This parameter is initially set to "No". Change to "Yes" to allow Adult Content results to appear when matching videos to the Gracenote TMS database.
  • Show Roku Search Sports Content - This parameter is initially set to "No". Change to "Yes" to allow Sports Content results to appear when matching videos to the Gracenote TMS database. Because of the large number of sports items in the Gracenote TMS database, setting this parameter to "Yes" may prevent non-sports results from appearing in the list of potential matches.
  • Roku Search Feed URL Style - This parameter determines which of two available Search Feed URL styles is displayed when the magnifying-glass icon on the Channels page is selected. The two Search Feed URL styles may be used interchangeably, however it undesireable to change the Search Feed URL after it has been provided to Roku.

    The "Specify a unique 3-digit ID..." option must be selected if your design flow uses clones to perform channel updates, as it allows the same Search Feed URL to be re-assigned to different instances of a channel. This is the default and recommended option which is used in the tutorial above.

    The "Use the Channel ID..." option may be selected if your design flow always updates channels in-place, and the published channel always has the same 36-character Channel ID. This option does not use the 3-digit ID.

  • Roku Search Match List Sort Order - This parameter determines the order in which the titles appear in the list of potential matches. "Display the matches alphabetically" is the default. "Display the matches best match first" often provides the matching item at the top of the list, but can make it difficult to locate potential matches that are further down in the list.


The Roku Developer Forum is a useful resource for developers of SDK channels, and is a great place to ask questions.

Want to know more about how to build an SDK Roku channel? Check out this Roku Custom SDK Walk-Through for all of the details.


Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.



Access Code: U463
Check out Instant TV Channel by adding our latest demonstration channel to your Roku player, or watch the YouTube video.

Need help with your Roku?

We are unable to provide technical support for your Roku device.

Please visit www.roku.com for assistance.



Instant TV Channel is not affiliated with nor endorsed by Roku Inc.