songstats

README

Songstats Go client library

Documentation

Overview

Package songstats provides a minimal client library for interacting with the Songstats API, either directly or via RapidAPI.

Index

• Constants
• func HTTPStatus(err error) int
• type ArtistHistoricStatsResponse
• type ArtistInfo
• type ArtistInfoResponse
• type Client
  • func New(apiKey string, options ...ClientOption) (*Client, error)
  • func (c *Client) ArtistHistoricStats(ctx context.Context, options ...RequestOption) (*ArtistHistoricStatsResponse, error)
  • func (c *Client) ArtistInfo(ctx context.Context, options ...RequestOption) (*ArtistInfo, error)
• type ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithHTTPClient(client *http.Client) ClientOption
  • func WithHardRateLimit() ClientOption
  • func WithRemainingRateLimit(remaining int) ClientOption
  • func WithRetry(dur time.Duration) ClientOption
• type Link
• type RequestOption
  • func WithAggregates() RequestOption
  • func WithEndDate(date time.Time) RequestOption
  • func WithSongstatsArtistID(id string) RequestOption
  • func WithSources(source ...string) RequestOption
  • func WithSpotifyArtistID(id string) RequestOption
  • func WithStartDate(date time.Time) RequestOption
• type Stat
• type StatData
• type StatHistory
  • func (h *StatHistory) UnmarshalJSON(data []byte) error

Constants

const (
	// DefaultEndpoint is the base API endpoint for the Songstats API.
	DefaultEndpoint = "https://api.songstats.com/enterprise/v1"
	// RapidAPIEndpoint is the base API endpoint for the Songstats API when
	// connecting via [RapidAPI]. Pass this to [WithBaseURL] to use RapidAPI.
	//
	// [RapidAPI]: https://rapidapi.com/songstats-app-songstats-app-default/api/songstats
	RapidAPIEndpoint = "https://songstats.p.rapidapi.com/"
)

Functions

func HTTPStatus

func HTTPStatus(err error) int

HTTPStatus returns the HTTP status code for an error, or 0 if the error is nil, or -1 if the error has no status code.

Types

type ArtistHistoricStatsResponse

type ArtistHistoricStatsResponse struct {
	Result     string     `json:"result"`
	Message    string     `json:"message"`
	Stats      []Stat     `json:"stats"`
	ArtistInfo ArtistInfo `json:"artist_info"`
	SourceIDs  []string   `json:"source_ids"`
}

ArtistHistoricStatsResponse represents the response from the Songstats API for the Get Historic Stats endpoint.

type ArtistInfo

type ArtistInfo struct {
	ID      string   `json:"songstats_artist_id"`
	Avatar  string   `json:"avatar"`
	Name    string   `json:"name"`
	SiteURL string   `json:"site_url"`
	Links   []Link   `json:"links"`
	Genres  []string `json:"genres"`
}

ArtistInfo contains information about a SongStats artist.

type ArtistInfoResponse

type ArtistInfoResponse struct {
	Result     string      `json:"result"`
	Message    string      `json:"message"`
	ArtistInfo *ArtistInfo `json:"artist_info"`
}

ArtistInfoResponse is the response from the SongStats API for the Get Artist Info endpoint.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a Songstats API client.

func New

func New(apiKey string, options ...ClientOption) (*Client, error)

New creates a new Songstats API client. apiKey is required, and is added to all outbound requests as both the Apikey and X-Rapidapi-Key HTTP headers.

func (*Client) ArtistHistoricStats

func (c *Client) ArtistHistoricStats(ctx context.Context, options ...RequestOption) (*ArtistHistoricStatsResponse, error)

ArtistHistoricStats returns historic information of an artist filtered by source. Requires either WithSongstatsArtistID or WithSpotifyArtistID.

Also supports: WithSources, WithEndDate, WithStartDate, WithAggregates.

func (*Client) ArtistInfo

func (c *Client) ArtistInfo(ctx context.Context, options ...RequestOption) (*ArtistInfo, error)

ArtistInfo returns metadata information of an artist. Requires either WithSongstatsArtistID or WithSpotifyArtistID.

type ClientOption

type ClientOption func(*Client) error

ClientOption is a client option.

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets the base URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets the HTTP client.

func WithHardRateLimit

func WithHardRateLimit() ClientOption

WithHardRateLimit enables hard rate limiting for RapidAPI. This emulates server-side rate limiting, by returning a synthetic 429 response when the client has exceeded its rate limit as indicated by the x-ratelimit-requests-remaining header returned by RapidAPI. This option has no effect when communicating directly to Seatgeek.

This IS NOT a fool proof solution! It is still possible to exceed the rate limit, especially if you have multiple clients running in parallel, or for short-lived cliens. You may also wish to use WithRemainingRateLimit if you are tracking rate limits across multiple clients externally.

func WithRemainingRateLimit

func WithRemainingRateLimit(remaining int) ClientOption

WithRemainingRateLimit sets the remaining rate limit for the client. This option is useful when tracking rate limits across multiple clients, and should be used in conjunction with WithHardRateLimit. Pass in the last value received from the x-ratelimit-requests-remaining header from RapidAPI.

func WithRetry

func WithRetry(dur time.Duration) ClientOption

WithRetry enables automatic retries for up to to the specified duration, when a request fails due to rate limiting. For a single synchronous client, a value of 2 seconds should be sufficient to work around the per-second rate limit

type Link

type Link struct {
	Source     string `json:"source"`
	ExternalID string `json:"external_id"`
	URL        string `json:"url"`
}

Link represents a link to an external site.

type RequestOption

type RequestOption func(url.Values) error

RequestOption is an option for an API request.

func WithAggregates

func WithAggregates() RequestOption

WithAggregates includes data points aggregated by Songstats like playlists_current, playlists_reach_current, charts_current, etc.

func WithEndDate

func WithEndDate(date time.Time) RequestOption

WithEndDate specifies the end date for the requested data. Only the year, day, and month are used.

func WithSongstatsArtistID

func WithSongstatsArtistID(id string) RequestOption

WithSongstatsArtistID specifies the Songstats ID of artist being requested.

func WithSources

func WithSources(source ...string) RequestOption

WithSources specifies one or more sources that data is being requested for. May also be "all" for all sources, which is also the default behavior.

func WithSpotifyArtistID

func WithSpotifyArtistID(id string) RequestOption

WithSpotifyArtistID specifies the Spotify ID of the artist being requested.

func WithStartDate

func WithStartDate(date time.Time) RequestOption

WithStartDate specifies the start date for the requested data. Only the year, day, and month are used.

type Stat

type Stat struct {
	Source string   `json:"source"`
	Data   StatData `json:"data"`
}

Stat represents a single statistic in the ArtistHistoricStatsResponse.

type StatData

type StatData struct {
	History []StatHistory `json:"history"`
}

StatData represents a collection of historical data points for a single data source.

type StatHistory

type StatHistory struct {
	Date   time.Time        `json:"date"`
	Values map[string]int64 `json:"-"`
}

StatHistory represents a single data point in the StatData.

func (*StatHistory) UnmarshalJSON

func (h *StatHistory) UnmarshalJSON(data []byte) error

UnmarshalJSON handles custom JSON unmarshalling for StatHistory.