Stream Categories

Learn to search for and retrieve top categories using the Twitch API.

We'll cover the following

Each stream has at least one game—or category as they’re called on Twitch—associated with it that the streamer will be playing online. Streamers can also divide their streams into chapters, where each chapter has a separate category associated with it. This helps viewers find their streams based on the games they want to see being played.

Search for games

Since there's a massive number of video games, there's a vast number of categories on Twitch. Fortunately, we can use the category search endpoint to search through these games.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/search/categories

All calls to this endpoint must be authorized with either an app or a user access token. We'll use an app access token in this lesson.

Request parameters

This endpoint takes a single required parameter, the search query, and a couple of optional parameters we can use to filter the search results. The table below gives an overview of these parameters:

Parameter

Type

Category

Description

query

String

Required

This is the search query on which the search will be performed. This must be a URL-encoded string.

after

String

Optional

This is a cursor value for forward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this value in the after parameter to return the page of results after the page specified by the cursor.

first

Integer

Optional

This is the number of results to be returned per page, with a maximum of 100 results per page. Its default value is 20.

Let's make a sample call to this endpoint, authorizing ourselves with an app access token. We can change the value of the query parameter on line 12 to a string of our liking.

Note: If your access token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/search/categories");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing the search query
const queryParameters = new URLSearchParams({
  query: "pokemon",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function searchCategories() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
searchCategories();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the request using the query parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 20–28: We define a function called searchCategories to make a call to the category search endpoint.

    • Lines 21–25: We make a call to the endpoint within a try block and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the searchCategories function.

The API responds with a list of games that either fully or partly match the search query. Since we use pokemon as our search query, we receive a list of categories with "pokemon" in their names.

Response fields

The JSON response has two top-level properties—data and pagination. The search results are contained in the data property in the form of an array of category objects. The table below discusses the properties of these objects:

Property

Type

Description

id

String

This is the ID of the game.

name

String

This is the name of the game.

boxart_url

String

This is the static URL of the game's box art.

Fetch top games

Both viewers and streamers are interested in the current trending games. Viewers are naturally interested in watching their favorite streamers play trending games. For streamers, playing these games is a way to get more viewers to watch their streams.

The list of top games is constantly changing, but we can easily retrieve the current list of most-viewed games on Twitch using the top games endpoint.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/games/top

All calls to this endpoint need to be authorized with either an app access token or a user access token. We'll use an app access token in this lesson.

Request parameters

It doesn’t require any parameters. However, we can provide a few optional parameters to filter the search results. The table below gives an overview of these parameters:

Parameter

Type

Category

Description

after

String

Optional

This is a cursor value for forward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this value in the after parameter to return the page of results after the page specified by the cursor.

before

String

Optional

This is a cursor value for backward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this value in the before parameter to return the page of results after the page specified by the cursor.

first

Integer

Optional

This is the number of results to be returned per page, with a maximum of 100 results per page. Its default value is 20.

Let's make a sample call to this endpoint, authorizing ourselves with an app access token.

Note: If your access token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/games/top");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getTopGames() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getTopGames();

In the code above, we perform the following:

  • Lines 10–13: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 15–22: We define a function called getTopGames to make a call to the top games endpoint.

    • Lines 16–19: We make a call to the endpoint within a try block and print the response from the API.

    • Lines 19–21: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 24: We invoke the getTopGames function.

The API responds with a list of games sorted by the number of viewers, with the most-viewed category at the top. This response is structured the same way as the response from the category search endpoint. The data property contains an array of category objects and the pagination property contains a cursor value.

Get game details

We can send a GET request to the games endpoint to retrieve the details of games.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/games

All calls to this endpoint need to be authorized with either an app access token or a user access token. We'll use an app access token in this lesson.

Request parameters

For a request to be successful, we must provide at least one of the following parameters:

Parameter

Type

Category

Description

id

String

Required

This is the ID of the game. We can provide a maximum of 100 game IDs.

name

String

Required

This is the full name of the game. It doesn’t return partial matches. We can provide a maximum of 100 names.

Although both these parameters are listed as required parameters, only one of them is required to make a call. We can use only the id parameter, only the name parameter, or both.

Let's make a sample call to this endpoint using the games from the table below:

Game

ID

Just Chatting

509658

VALORANT

516575

League of Legends

21779

Fortnite

33214

We can replace the values of the id and name parameters on lines 12 and 13, respectively, with values from the table.

Note: If your access token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/games");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing both the id and name parameters to fetch game details
const queryParameters = new URLSearchParams({
  id: "509658",
  name: "League of Legends",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getGameDetails() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getGameDetails();

In the code above, we perform the following:

  • Lines 11–14: We define the query parameters for the request using the id and name parameters.

  • Lines 16–19: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 21–29: We define a function called getGameDetails to make a call to the games endpoint.

    • Lines 22–26: We make a call to the endpoint within a try block and print the response from the API.

    • Lines 26–28: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 31: We invoke the getGameDetails function.

The API responds with the details of each game we passed as parameters to the request. The response is structured similarly to the response from the category search endpoint. The only difference here is that the pagination property is absent.