go_itunes_api

README

go-itunes-api

Go client for iTunes search API.

Documentation.

TODO:

• add tests
• add http options
• add error handling (specify error)
• add http req-resp logging
• impl lookup

Documentation

Index

• Constants
• type API
• type Attribute
• type Client
  • func NewClient(opt ClientOption) (*Client, error)
  • func (c *Client) Lookup(ctx context.Context, r LookupRequest) (LookupResponse, error)
  • func (c *Client) Search(ctx context.Context, r SearchRequest) (SearchResponse, error)
• type ClientOption
• type Entity
• type Kind
• type LookupRequest
• type LookupResponse
• type MediaType
• type Result
• type Results
• type SearchRequest
  • func (r SearchRequest) GetURLValues() url.Values
  • func (r *SearchRequest) Validate() error
• type SearchResponse

Constants

const (
	APIPath    = "https://itunes.apple.com"
	SearchPath = "/search"
	US         = "US"
)

const DefaultHTTPTimeout = 60 * time.Second

Types

type API

type API interface {
	Search(ctx context.Context, r SearchRequest) (SearchResponse, error)
	Lookup(ctx context.Context, r LookupRequest) (LookupResponse, error)
}

type Attribute

type Attribute string

const (
	AttributeActorTerm         Attribute = "actorTerm"
	AttributeAlbumTerm         Attribute = "albumTerm"
	AttributeAllArtistTerm     Attribute = "allArtistTerm"
	AttributeAllTrackTerm      Attribute = "allTrackTerm"
	AttributeArtistTerm        Attribute = "artistTerm"
	AttributeAuthorTerm        Attribute = "authorTerm"
	AttributeComposerTerm      Attribute = "composerTerm"
	AttributeDescriptionTerm   Attribute = "descriptionTerm"
	AttributeDirectorTerm      Attribute = "directorTerm"
	AttributeFeatureFilmTerm   Attribute = "featureFilmTerm"
	AttributeGenreIndex        Attribute = "genreIndex"
	AttributeKeywordsTerm      Attribute = "keywordsTerm"
	AttributeLanguageTerm      Attribute = "languageTerm"
	AttributeMixTerm           Attribute = "mixTerm"
	AttributeMovieArtistTerm   Attribute = "movieArtistTerm"
	AttributeMovieTerm         Attribute = "movieTerm"
	AttributeProducerTerm      Attribute = "producerTerm"
	AttributeRatingIndex       Attribute = "ratingIndex"
	AttributeRatingTerm        Attribute = "ratingTerm"
	AttributeReleaseYearTerm   Attribute = "releaseYearTerm"
	AttributeShortFilmTerm     Attribute = "shortFilmTerm"
	AttributeShowTerm          Attribute = "showTerm"
	AttributeSoftwareDeveloper Attribute = "softwareDeveloper"
	AttributeSongTerm          Attribute = "songTerm"
	AttributeTitleTerm         Attribute = "titleTerm"
	AttributeTvEpisodeTerm     Attribute = "tvEpisodeTerm"
	AttributeTvSeasonTerm      Attribute = "tvSeasonTerm"
)

type Client

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

func NewClient

func NewClient(opt ClientOption) (*Client, error)

func (*Client) Lookup

func (c *Client) Lookup(ctx context.Context, r LookupRequest) (LookupResponse, error)

func (*Client) Search

func (c *Client) Search(ctx context.Context, r SearchRequest) (SearchResponse, error)

type ClientOption

type ClientOption struct {
	Host    string
	Timeout time.Duration
}

type Entity

type Entity string

const (
	EntityAlbum           Entity = "album"
	EntityAllArtist       Entity = "allArtist"
	EntityAllTrack        Entity = "allTrack"
	EntityAudiobook       Entity = "audiobook"
	EntityAudiobookAuthor Entity = "audiobookAuthor"
	EntityEbook           Entity = "ebook"
	EntityIPadSoftware    Entity = "iPadSoftware"
	EntityMacSoftware     Entity = "macSoftware"
	EntityMix             Entity = "mix"
	EntityMovie           Entity = "movie"
	EntityMovieArtist     Entity = "movieArtist"
	EntityMusicArtist     Entity = "musicArtist"
	EntityMusicTrack      Entity = "musicTrack"
	EntityMusicVideo      Entity = "musicVideo"
	EntityPodcast         Entity = "podcast"
	EntityPodcastAuthor   Entity = "podcastAuthor"
	EntityShortFilm       Entity = "shortFilm"
	EntityShortFilmArtist Entity = "shortFilmArtist"
	EntitySoftware        Entity = "software"
	EntitySong            Entity = "song"
	EntityTvEpisode       Entity = "tvEpisode"
	EntityTvSeason        Entity = "tvSeason"
)

type Kind

type Kind string

const (
	KindAlbum              Kind = "album"
	KindArtist             Kind = "artist"
	KindBook               Kind = "book"
	KindCoachedAudio       Kind = "coached-audio"
	KindFeatureMovie       Kind = "feature-movie"
	KindInteractiveBooklet Kind = "interactive-booklet"
	KindMusicVideo         Kind = "music-video"
	KindPdf                Kind = "pdf"
	KindPodcast            Kind = "podcast"
	KindPodcastEpisode     Kind = "podcast-episode"
	KindSoftwarePackage    Kind = "software-package"
	KindSong               Kind = "song"
	KindTvEpisode          Kind = "tv-episode"
)

type LookupRequest

type LookupRequest struct{}

type LookupResponse

type LookupResponse struct {
	Results Results
}

type MediaType

type MediaType string

const (
	MediaTypeMovie      MediaType = "movie"
	MediaTypePodcast    MediaType = "podcast"
	MediaTypeMusic      MediaType = "music"
	MediaTypeMusicVideo MediaType = "musicVideo"
	MediaTypeAudiobook  MediaType = "audiobook"
	MediaTypeShortFilm  MediaType = "shortFilm"
	MediaTypeTvShow     MediaType = "tvShow"
	MediaTypeSoftware   MediaType = "software"
	MediaTypeEbook      MediaType = "ebook"
	MediaTypeAll        MediaType = "all"
)

type Result

type Result struct {
	ArtistId                int       `json:"artistId,omitempty,omitempty"`
	ArtistName              string    `json:"artistName,omitempty"`
	ArtistViewUrl           string    `json:"artistViewUrl,omitempty,omitempty"`
	ArtworkUrl100           string    `json:"artworkUrl100,omitempty"`
	ArtworkUrl30            string    `json:"artworkUrl30,omitempty"`
	ArtworkUrl60            string    `json:"artworkUrl60,omitempty"`
	CollectionArtistId      int       `json:"collectionArtistId,omitempty,omitempty"`
	CollectionArtistName    string    `json:"collectionArtistName,omitempty,omitempty"`
	CollectionArtistViewUrl string    `json:"collectionArtistViewUrl,omitempty,omitempty"`
	CollectionCensoredName  string    `json:"collectionCensoredName,omitempty,omitempty"`
	CollectionExplicitness  string    `json:"collectionExplicitness,omitempty"`
	CollectionHdPrice       float64   `json:"collectionHdPrice,omitempty,omitempty"`
	CollectionId            int       `json:"collectionId,omitempty,omitempty"`
	CollectionName          string    `json:"collectionName,omitempty,omitempty"`
	CollectionPrice         float64   `json:"collectionPrice,omitempty"`
	CollectionViewUrl       string    `json:"collectionViewUrl,omitempty,omitempty"`
	ContentAdvisoryRating   string    `json:"contentAdvisoryRating,omitempty,omitempty"`
	Country                 string    `json:"country,omitempty"`
	Currency                string    `json:"currency,omitempty"`
	DiscCount               int       `json:"discCount,omitempty,omitempty"`
	DiscNumber              int       `json:"discNumber,omitempty,omitempty"`
	HasITunesExtras         bool      `json:"hasITunesExtras,omitempty,omitempty"`
	IsStreamable            bool      `json:"isStreamable,omitempty,omitempty"`
	Kind                    Kind      `json:"kind,omitempty"`
	LongDescription         string    `json:"longDescription,omitempty,omitempty"`
	PreviewUrl              string    `json:"previewUrl,omitempty"`
	PrimaryGenreName        string    `json:"primaryGenreName,omitempty"`
	ReleaseDate             time.Time `json:"releaseDate,omitempty"`
	ShortDescription        string    `json:"shortDescription,omitempty,omitempty"`
	TrackCensoredName       string    `json:"trackCensoredName,omitempty"`
	TrackCount              int       `json:"trackCount,omitempty,omitempty"`
	TrackExplicitness       string    `json:"trackExplicitness,omitempty"`
	TrackHdPrice            float64   `json:"trackHdPrice,omitempty,omitempty"`
	TrackHdRentalPrice      float64   `json:"trackHdRentalPrice,omitempty,omitempty"`
	TrackId                 int       `json:"trackId,omitempty"`
	TrackName               string    `json:"trackName,omitempty"`
	TrackNumber             int       `json:"trackNumber,omitempty,omitempty"`
	TrackPrice              float64   `json:"trackPrice,omitempty"`
	TrackRentalPrice        float64   `json:"trackRentalPrice,omitempty,omitempty"`
	TrackTimeMillis         int       `json:"trackTimeMillis,omitempty"`
	TrackViewUrl            string    `json:"trackViewUrl,omitempty"`
	WrapperType             string    `json:"wrapperType,omitempty"`
}

Result represents a single search result.

https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/UnderstandingSearchResults.html#//apple_ref/doc/uid/TP40017632-CH8-SW1

type Results

type Results struct {

	// The number of results that match the search term.
	ResultCount int `json:"resultCount,omitempty"`

	// Results is an array of objects that contain the search results.
	Results []Result `json:"results,omitempty"`
}

type SearchRequest

type SearchRequest struct {

	// The text string you want to search for. For example: jack+johnson.
	//
	// Required.
	Term string

	// The two-letter country code for the store you want to search. The search uses
	// the default store front for the specified country. For example: US. The
	// default is US. See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for a list
	// of ISO Country Codes.
	//
	// Required.
	Country string

	// The media type you want to search for. For example: movie. The default is all.
	//
	// Optional.
	Media MediaType

	// The type of results you want returned, relative to the specified media type.
	// For example: movieArtist for a movie media type search. The default is the
	// track entity associated with the specified media type.
	//
	// Optional.
	Entity Entity

	// The attribute you want to search for in the stores, relative to the specified
	// media type. For example, if you want to search for an artist by name specify
	// entity=allArtist&attribute=allArtistTerm. In this example, if you search for
	// term=maroon, iTunes returns “Maroon 5” in the search results, instead of all
	// artists who have ever recorded a song with the word “maroon” in the title. The
	// default is all attributes associated with the specified media type.
	//
	// Optional.
	Attribute Attribute

	// The name of the Javascript callback function you want to use when returning
	// search results to your website.
	//
	// Required for cross-site searches.
	Callback string

	// The number of search results you want the iTunes Store to return. For example:
	// 25. The default is 50.
	//
	// Optional.
	Limit int

	// The language, English or Japanese, you want to use when returning search
	// results. Specify the language using the five-letter codename. For example:
	// en_us. The default is en_us (English).
	//
	// Optional.
	Lang string

	// The search result key version you want to receive back from your search. The
	// default is 2.
	//
	// Optional.
	Version string

	// A flag indicating whether or not you want to include explicit content in your
	// search results. The default is Yes.
	//
	// Optional.
	Explicit bool
}

func (SearchRequest) GetURLValues

func (r SearchRequest) GetURLValues() url.Values

func (*SearchRequest) Validate

func (r *SearchRequest) Validate() error

type SearchResponse

type SearchResponse struct {
	Results Results
}