go-twitch/api/analytics/get_game_analytics.go

package analytics

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 GetGameAnalyticsParams struct {
	// The game’s client ID. If specified, the response contains a report for the specified game.
	// If not specified, the response includes a report for each of the authenticated user’s games.
	GameID *string `url:"game_id,omitempty"`

	// The type of analytics report to get. Possible values are:
	//
	// - overview_v2
	Type *string `url:"type,omitempty"`

	// The reporting window’s start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z).
	// If you specify a start date, you must specify an end date.
	//
	// The start date must be within one year of today’s date. If you specify an earlier date,
	// the API ignores it and uses a date that’s one year prior to today’s date. If you don’t specify a start and end date,
	// the report includes all available data for the last 365 days from today.
	//
	// The report contains one row of data for each day in the reporting window.
	StartedAt *time.Time `url:"started_at,omitempty"`

	// The reporting window’s end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z).
	// The report is inclusive of the end date.
	//
	// Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available,
	// you must specify an end date that’s earlier than today minus one to two days.
	// If not, the API ignores your end date and uses an end date that is today minus one to two days.
	EndedAt *time.Time `url:"ended_at,omitempty"`

	// The maximum number of report URLs to return per page in the response.
	// The minimum page size is 1 URL per page and the maximum is 100 URLs per page.The default is 20.
	//
	// NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.
	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
	//
	// This parameter is ignored if game_id parameter is set.
	After *types.Cursor `url:"after,omitempty"`
}

type GetGameAnalyticsResponse struct {
	// A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first).
	// The report contains one row of data per day of the reporting window; the report contains rows for only those days that the game was used.
	// A report is available only if the game was broadcast for at least 5 hours over the reporting period. The array is empty if there are no reports.
	Data []GameAnalyticsReport `json:"data"`

	// 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.
	Pagination types.Pagination `json:"pagination"`
}

type GameAnalyticsReport struct {
	// An ID that identifies the game that the report was generated for.
	GameID string `json:"game_id"`

	// The URL that you use to download the report. The URL is valid for 5 minutes.
	URL string `json:"URL"`

	// The type of report.
	Type string `json:"type"`

	// The reporting window’s start and end dates, in RFC3339 format.
	DateRange types.DateRange `json:"date_range"`
}

// Gets an analytics report for one or more games. The response contains the URLs used to download the reports (CSV files).
// Learn more: https://dev.twitch.tv/docs/insights
//
// Requires a user access token that includes the analytics:read:games scope.
func (a *Analytics) GetGameAnalytics(ctx context.Context, params GetGameAnalyticsParams) (*GetGameAnalyticsResponse, error) {
	v, _ := query.Values(params)

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

	res, err := a.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 get game analytics (%d)", res.StatusCode)
	}

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

	return &data, nil
}