Stream Categories
Learn to search for and retrieve top categories using the Twitch API.
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 need to be authorized with either an app or a user access token. We'll use an app access token in this lesson.
Input 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 |
| String | Required | This is the search query on which the search will be performed. This must be a URL-encoded string. |
| 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 |
| 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 |
Example call
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 7 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.
headers = {'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}','Client-Id' : '{{CLIENT_ID}}'}parameters = {'query' : 'pokemon'}response = requests.get('https://api.twitch.tv/helix/search/categories',headers=headers, params=parameters).json()print(json.dumps(response, indent=4))
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 structure
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 |
| String | This is the ID of the game. |
| String | This is the name of the game. |
| 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. For viewers, they’re 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.
Input 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 |
| 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 |
| 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 |
| 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 |
Example call
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.
headers = {'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}','Client-Id' : '{{CLIENT_ID}}'}response = requests.get('https://api.twitch.tv/helix/games/top', headers=headers).json()print(json.dumps(response, indent=4))
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
Parameter | Type | Category | Description |
| String | Required | This is the ID of the game. We can provide a maximum of 100 game IDs. |
| 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 either use the id parameter on its own, only the name parameter, or even both.
Example call
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 7 and 8, 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.
headers = {'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}','Client-Id' : '{{CLIENT_ID}}'}parameters = {'id' : '509658','name' : 'League of Legends'}response = requests.get('https://api.twitch.tv/helix/games',headers=headers, params=parameters).json()print(json.dumps(response, indent=4))
The API responds with the details of each game that we passed as parameters to the request. The response is structured the same way as the response from the category search endpoint. The only difference here is that the pagination property is absent.