How to fetch Data from the Playout API

This guide provides a step-by-step walkthrough on how to fetch playout data, such as episode information and content groups, using the Jay Playout API. This process typically involves initiating a tracking session, identifying the specific episode you're interested in, and then fetching detailed data for that episode.

Prerequisites

Before you begin, ensure you have the following:

• playoutId: This is a unique identifier for the streaming platform, which you should receive from Jay.
• episodeName: The human-readable name of the episode you want to fetch data for (e.g., "The Pilot Episode"). This is typically known from your content curation process.

The episodeId (an internal identifier for the episode) will be retrieved during the process.

Content Structure

The content in the Jay marketplace is structured in multiple ways. Here are two common options, that can be combined or used separately:

• Menu Based Content: This is typically used for main menus or navigation sections, where content is grouped by categories or themes. The content stays the same across the whole episode, and is used to navigate through the content.

• Time Based Content: This is used show different content depending on the current time code of the episode. This is useful for interactive content, where the user can pause the video and explore different items related to the current scene or time code.

• Menu Based Content
• Time Based Content

First-Steps Guide

1. Obtain a Tracking Session

A tracking session is used to correlate user actions and gather analytics. You should initiate a new session or retrieve an existing one.

• To initiate a new session, make a POST request. The API will respond with session details and attempt to set a __Secure-jay_tracking cookie.
• To retrieve an existing session (if the client might already have one), make a GET request. The API checks for the session in cookies or headers.

2. Find the episodeId

Once you have a tracking session, you need to find the internal episodeId for the desired episodeName.

• Fetch the list of all available episodes for your playoutId.
• Iterate through the list on the client-side to find the episode that matches your episodeName and extract its id (which is the episodeId).

API Endpoint:

• GET /playouts/{playoutId}/episodes

Example (Fetch Episodes):

Replace {playoutId} with your actual playout ID.

curl -X GET "https://your-api-domain/v1/playouts/{playoutId}/episodes" \
     -H "X-API-Key: your_api_key_here" \
     -H "Cookie: __Secure-jay_tracking=your_session_value_here"
# or -H "__Secure-jay_tracking: your_session_value_here"

Example (Client-side JavaScript to find episodeId):

async function findEpisodeId(playoutId, episodeName, trackingSessionValue) {
  const response = await fetch(`/v1/playouts/${playoutId}/episodes`, {
    headers: {
      // Choose one: Cookie or custom header
      'Cookie': `__Secure-jay_tracking=${trackingSessionValue}`,
      'X-API-Key': 'your_api_key_here'
      // '__Secure-jay_tracking': trackingSessionValue
    }
  });
  if (!response.ok) {
    console.error("Failed to fetch episodes:", await response.text());
    return null;
  }
  const episodes = await response.json(); // Assuming response is an array of episode objects

  // The actual structure of an episode object might vary.
  // Consult the 'PlayoutEpisodeEntry' schema in /apis/playout/@latest/openapi.json.
  // Let's assume each episode object has 'name' and 'id' properties.
  const targetEpisode = episodes.find(ep => ep.name === episodeName); // Adjust 'ep.name' if property is different

  if (targetEpisode) {
    return targetEpisode.id; // Adjust 'ep.id' if property is different
  } else {
    console.error(`Episode with name "${episodeName}" not found.`);
    return null;
  }
}

// Usage:
// const playoutId = "your_playout_id";
// const episodeName = "The Pilot Episode";
// const trackingValue = "retrieved_session_value";
// findEpisodeId(playoutId, episodeName, trackingValue).then(episodeId => {
//   if (episodeId) {
//     console.log("Found episodeId:", episodeId);
//     // Proceed to next steps
//   }
// });

curl -i -X GET \
  'https://docs.jay-metadata.com/v1/playouts/{playoutId}/episodes?episode=string&movieOrSeries=string&provider=string&targetDevice=string' \
  -H 'X-API-Key: string' \
  -H '__Secure-jay_tracking: __Secure-jay_tracking=eyJzZX...'

{
  "data": [
    { … }
  ]
}

3. Fetch detailed Episode Information

With the playoutId and the retrieved episodeId, you can now fetch comprehensive details for that specific episode.

API Endpoint:

• GET /playouts/{playoutId}/episodes/{episodeId}

Example (Fetch Episode Details):

Replace {playoutId} and {episodeId} with actual values.

curl -X GET "https://your-api-domain/v1/playouts/{playoutId}/episodes/{episodeId}" \
     -H "X-API-Key: your_api_key_here" \
     -H "Cookie: __Secure-jay_tracking=your_session_value_here"

The response will contain detailed information about the episode, as defined by the PlayoutEpisode schema.

4. Fetch Episode Groups (e.g., for Main Menu)

To construct UI elements like a main menu or categorized content sections, you can fetch groups associated with the episode.

• Fetch all groups for the episode.
• On the client-side, you will need to filter or interpret these groups to build your desired UI. For example, a group intended for a "main menu" might be identified by a specific name, type, or a custom attribute within its properties (e.g., a flag like isMainMenu: true if such a convention exists in your data). Consult the PlayoutGroup schema and your content curation guidelines.

API Endpoint:

• GET /playouts/{playoutId}/episodes/{episodeId}/groups

Example (Fetch Episode Groups):

Replace {playoutId} and {episodeId} with actual values.

curl -X GET "https://your-api-domain/v1/playouts/{playoutId}/episodes/{episodeId}/groups" \
     -H "X-API-Key: your_api_key_here" \
     -H "Cookie: __Secure-jay_tracking=your_session_value_here"

Example (Client-side JavaScript to identify main menu groups):

async function getMainMenuGroups(playoutId, episodeId, trackingSessionValue) {
  const response = await fetch(`/v1/playouts/${playoutId}/episodes/${episodeId}/groups`, {
    headers: {
      'Cookie': `__Secure-jay_tracking=${trackingSessionValue}`,
      'X-API-Key': 'your_api_key_here'
    }
  });
  if (!response.ok) {
    console.error("Failed to fetch groups:", await response.text());
    return [];
  }
  const groups = await response.json(); // Assuming response is an array of group objects

  // Example: Filter groups that are designated for the main menu.
  // This logic depends on how main menu groups are identified in your data
  // (e.g., by name, a specific property, or type).
  // Refer to the 'PlayoutGroup' schema.
  const mainMenuGroups = groups.filter(group => {
    // return group.name === "Main Menu" || (group.attributes && group.attributes.isMainMenu === true);
    // Adjust the condition above based on your actual data structure for identifying main menu groups.
    // For this example, let's assume a group named "Main Menu" is the target.
    return group.name === "Main Menu"; // Adjust 'group.name' if property is different
  });

  return mainMenuGroups;
}

// Usage:
// getMainMenuGroups(playoutId, episodeId, trackingValue).then(menuGroups => {
//   console.log("Main menu groups:", menuGroups);
//   // Use menuGroups to build your UI
// });

Further Data Fetching

The Playout API provides many other endpoints to fetch specific data related to an episode, such as:

• Products: /playouts/{playoutId}/episodes/{episodeId}/products
• Actors: /playouts/{playoutId}/episodes/{episodeId}/actors
• Scenes: /playouts/{playoutId}/episodes/{episodeId}/scenes
• And more (chapters, locations, costumes, etc.)

Refer to the Playout API documentation for a complete list of available endpoints and their details. Remember to replace placeholders like {playoutId}, {episodeId}, and {productId} with actual values in your requests.