go-twitch/api/search/search_channels.go

package search

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"

	"github.com/google/go-querystring/query"
	"go.fifitido.net/twitch/api/endpoint"
	"go.fifitido.net/twitch/api/types"
)

type SearchChannelsParams struct {
	// The URI-encoded search string. For example, encode #archery as %23archery and search strings like angel of death as angel%20of%20death.
	Query string `url:"query,omitempty"`

	// A Boolean value that determines whether the response includes only channels that are currently streaming live.
	// Set to true to get only channels that are streaming live; otherwise, false to get live and offline channels.
	// The default is false.
	LiveOnly *bool `url:"live_only,omitempty"`

	// 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.
	First *int `url:"first,omitempty"`

	// The cursor used to get the next page of results.
	// The Pagination object in the response contains the cursor’s value.
	// Read More: https://dev.twitch.tv/docs/api/guide#pagination
	After *types.Cursor `url:"after,omitempty"`
}

type SearchChannelsResponse struct {
	// The list of channels that match the query. The list is empty if there are no matches.
	Data []struct {
		// The ISO 639-1 two-letter language code of the language used by the broadcaster.
		// For example, en for English. If the broadcaster uses a language not in the list of supported stream languages, the value is other.
		BroadcasterLanguage string `json:"broadcaster_language"`

		// The broadcaster’s login name.
		BroadcasterLogin string `json:"broadcaster_login"`

		// The broadcaster’s display name.
		DisplayName string `json:"display_name"`

		// The ID of the game that the broadcaster is playing or last played.
		GameID string `json:"game_id"`

		// The name of the game that the broadcaster is playing or last played.
		GameName string `json:"game_name"`

		// An ID that uniquely identifies the channel (this is the broadcaster’s ID).
		ID string `json:"id"`

		// A Boolean value that determines whether the broadcaster is streaming live. Is true if the broadcaster is streaming live; otherwise, false.
		IsLive bool `json:"is_live"`

		// The tags applied to the channel.
		Tags []string `json:"tags"`

		// A URL to a thumbnail of the broadcaster’s profile image.
		ThumbnailURL string `json:"thumbnail_url"`

		// The stream’s title. Is an empty string if the broadcaster didn’t set it.
		Title string `json:"title"`

		// The UTC date and time (in RFC3339 format) of when the broadcaster started streaming.
		// The string is empty if the broadcaster is not streaming live.
		StartedAt *time.Time `json:"started_at"`
	} `json:"data"`
}

// Gets the channels that match the specified query and have streamed content within the past 6 months.
//
// 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.
// However, if live_only is true, the API matches on the broadcaster’s name and category name.
//
// To match, the beginning of the broadcaster’s name or category must match the query string. The comparison is case insensitive.
// If the query string is angel_of_death, it matches all names that begin with angel_of_death.
// However, if the query string is a phrase like angel of death, it matches to names starting with angelofdeath or names starting with 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.
//
// Requires an app access token or user access token.
func (s *Search) SearchChannels(ctx context.Context, params *SearchChannelsParams) (*SearchChannelsResponse, error) {
	v, _ := query.Values(params)

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.Make(s.baseUrl, "search/channels", v), nil)
	if err != nil {
		return nil, err
	}

	res, err := s.client.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	statusOK := res.StatusCode >= 200 && res.StatusCode < 300
	if !statusOK {
		return nil, fmt.Errorf("failed to search channels (%d)", res.StatusCode)
	}

	var data SearchChannelsResponse
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		return nil, err
	}

	return &data, nil
}