Search - API Reference | Twitch Developers

Search Categories

Gets the games or categories that match the specified query.

A category matches if its name or one of its alternative names begins with the query string, if any word in its name begins with the query string, or if each word in the query string matches the beginning of a word in its name. For example, if the query string is love computer, the response includes any category whose name contains words that begin with love and computer. The comparison is case insensitive, and close misspellings can also match.

Endpoint

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

Authorization

Requires one of the following:

A user access token.
An app access token.

Query Parameters

queryStringRequired
The URI-encoded search string. For example, encode #archery as '%23archery' and search strings like angel of death as 'angel%20of%20death'.
firstInteger
The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

Response Body

dataObject[]
The list of games or categories that match the query. The list is empty if there are no matches.
Hide child attributesShow child attributes
- data.box_art_urlString
  A URL to an image of the game's box art or streaming category.
- data.nameString
  The name of the game or category.
- data.idString
  An ID that uniquely identifies the game or category.
paginationObject
Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More.
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Use the cursor to set the request's after query parameter.

Response Codes

200OK: Successfully retrieved the list of category names that matched the specified query string.
400Bad Request: The query query parameter is required.
401Unauthorized: The Authorization header is required and must contain an app access token or user access token.
The access token is not valid.
The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/search/categories?query=fort' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/search/categories?query=fort" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/search/categories?query=fort", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/search/categories",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "query": "fort",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/search/categories?query=fort", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/search/categories?query=fort");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/search/categories?query=fort");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/search/categories?query=fort")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "33214",
      "name": "Fortnite",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-52x72.jpg"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN"
  }
}

Search Channels

Gets the channels that match the specified query.

The fields that the API uses for comparison depends on the value that the live_only query parameter is set to. If live_only is false, the API matches on the broadcaster's login name and display name. However, if live_only is true, the API matches on the broadcaster's login name, display name, and the name of the category they're streaming.

If live_only is false, the broadcaster's login name or display name must begin with the query string. If live_only is true, the query string can also match the beginning of any word in those names or in the category name, and a phrase matches if each of its words does. The comparison is case insensitive, and close misspellings can also match. For example, the query string angel of death can match names that begin with angelofdeath or angel_of_death.

By default, the results include both live and offline channels. To get only live channels set the live_only query parameter to true.