Search for Channels

Learn to search for channels using the Twitch API.

We'll cover the following

Channel search

Every user on Twitch has a channel that is automatically created whenever a user signs up for a Twitch account. With countless channels across Twitch, it's necessary to have a way to search through them to find the one we're looking for. Fortunately, the Twitch API has us covered with the channel search endpoint.

The URL for this endpoint is as follows:

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

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 few other optional parameters that 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 we want to perform the search. 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.

live_only

Boolean

Optional

This determines whether only to return channels that are currently live. Its default value is false.

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/channels");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Defining the query to perform the search on
const queryParameters = new URLSearchParams({
  query: "twitch",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function searchChannels() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
searchChannels();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call 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 searchChannels to make a call to the channel search endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, 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 searchChannels function.

The API responds with a list of channels matching our search query. Since we use twitch as our search query, we receive a list of every channel with the string twitch in its name.

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 objects. The table below discusses the structure of these objects:

Property

Type

Description

broadcaster_language

String

This is the ISO-639-1 code for the language in which the channel broadcasts.

broadcaster_login

String

This is the channel user's login name.

display_name

String

This is the channel's display name.

game_id

String

This is the ID of the game the broadcaster is playing on stream. If the channel is offline, this is the game the user played on the last stream.

game_name

String

This is the name of the game the broadcaster is playing on stream. If the channel is offline, this is the game the user played on the last stream.

id

String

This is the ID of the channel user.

is_live

Boolean

This determines whether the channel is currently live streaming.

tag_ids

Array[String]

This is a list of IDs of tags that have been applied to the channel.

thumbnail_url

String

This is the static URL of the channel user's profile picture.

title

String

This is the title of the ongoing live stream. If the channel is offline, this is the title of the latest stream.

started_at

String

This is the UTC timestamp of when the ongoing live stream started. If the channel is offline, this is an empty string—"".