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"`
	ArtistName             string  `json:"artistName"`
	ArtistViewURL          string  `json:"artistViewUrl"`
	ArtworkURL100          string  `json:"artworkUrl100"`
	ArtworkURL60           string  `json:"artworkUrl60"`
	CollectionCensoredName string  `json:"collectionCensoredName"`
	CollectionExplicitness string  `json:"collectionExplicitness"`
	CollectionID           int     `json:"collectionId"`
	CollectionName         string  `json:"collectionName"`
	CollectionPrice        float64 `json:"collectionPrice"`
	CollectionViewURL      string  `json:"collectionViewUrl"`
	Country                string  `json:"country"`
	Currency               string  `json:"currency"`
	DiscCount              int     `json:"discCount"`
	DiscNumber             int     `json:"discNumber"`
	Kind                   Kind    `json:"kind"`
	PreviewURL             string  `json:"previewUrl"`
	PrimaryGenreName       string  `json:"primaryGenreName"`
	TrackCensoredName      string  `json:"trackCensoredName"`
	TrackCount             int     `json:"trackCount"`
	TrackExplicitness      string  `json:"trackExplicitness"`
	TrackID                int     `json:"trackId"`
	TrackName              string  `json:"trackName"`
	TrackNumber            int     `json:"trackNumber"`
	TrackPrice             float64 `json:"trackPrice"`
	TrackTimeMillis        int     `json:"trackTimeMillis"`
	TrackViewURL           string  `json:"trackViewUrl"`
	WrapperType            string  `json:"wrapperType"`
}

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
}