iTunes 搜索 API

这个搜索API允许你通过关键词在你的网站上搜索iTunes Store,App Store, iBooks Store and Mac App Store。你可以搜索各种内容;包括应用、图书、电影、广播、音乐、视频、有声读物以及TV节目。你也可以调用一个实名查询请求来创建内容库之间的映射和数字目录。开发者可以使用API里的推广的内容,包括歌曲预览,音乐录像,专辑封面和APP图标只用在推广的店面,不用于娱乐用途。从API里使用音乐样本及其他必须和店面徽章相似。条款和条件适用

这项计划允许当你的网站或者app获得点击后获得一些佣金。该项计划更多信息请查看:http://www.apple.com/itunes/affiliates

通过web去查找并且显示结果在web网站上。你必须创建一个搜索区域,通过完全限定的URL请求iTunes Store,并从返回的结果中解析JSON。然后将结果显示在web上。 完整的网址必须有以下格式:

https://itunes.apple.com/search?parameterkeyvalue

在参数里有一个或多个键值对,来详细说明你返回的结果。

构造一个参数键值对,你必须将每个参数的key等于(=)一个字符串value。例如:key1 =value1。创建一个字符串键值对,你必须将每对键值对用与(&)符号链接。例如:key1=value1&key2=value2&key3=value3

注:当您为网站创建搜索域和脚本时,你应该使用动态脚本标签你的XMLHTTP脚本调用请求。例如:

key1=value1

您可以使用下表定义的参数的key和value来搜索iTunes Store,App Store,iBooks商店和Mac App Store里面的内容:

Parameter Key Description Required Values
term The URL-encoded text string you want to search for. For example: jack+johnson. Y Any URL-encoded text string. Note: URL encoding replaces spaces with the plus (+) character and all characters except the following are encoded: letters, numbers, periods (.), dashes (-), underscores (_), and asterisks (*).
country 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. Y See http://en.wikipedia.org/wiki/ ISO_3166-1_alpha-2 for a list of ISO Country Codes.
media The media type you want to search for. For example: movie. The default is all. N movie, podcast, music, musicVideo, audiobook, shortFilm, tvShow, software, ebook, all
entity 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. N The following entities are available for each media type:moviemovieArtist, moviepodcastpodcastAuthor, podcastmusicmusicArtist, musicTrack, album, musicVideo, mix, song Please note that “musicTrack” can include both songs and music videos in the resultsmusicVideomusicArtist, musicVideoaudiobookaudiobookAuthor, audiobookshortFilmshortFilmArtist, shortFilmtvShowtvEpisode, tvSeasonsoftwaresoftware, iPadSoftware, macSoftwareebookebookallmovie, album, allArtist, podcast, musicVideo, mix, audiobook, tvSeason, allTrack
attribute 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. N The following attributes are available for each media type:movieactorTerm, genreIndex, artistTerm, shortFilmTerm, producerTerm, ratingTerm, directorTerm, releaseYearTerm, featureFilmTerm, movieArtistTerm, movieTerm, ratingIndex, descriptionTermpodcasttitleTerm, languageTerm, authorTerm, genreIndex, artistTerm, ratingIndex, keywordsTerm, descriptionTermmusicmixTerm, genreIndex, artistTerm, composerTerm, albumTerm, ratingIndex, songTermmusicVideogenreIndex, artistTerm, albumTerm, ratingIndex, songTermaudiobooktitleTerm, authorTerm, genreIndex, ratingIndexshortFilmgenreIndex, artistTerm, shortFilmTerm, ratingIndex, descriptionTermsoftwaresoftwareDevelopertvShowgenreIndex, tvEpisodeTerm, showTerm, tvSeasonTerm, ratingIndex, descriptionTermallactorTerm, languageTerm, allArtistTerm, tvEpisodeTerm, shortFilmTerm, directorTerm, releaseYearTerm, titleTerm, featureFilmTerm, ratingIndex, keywordsTerm, descriptionTerm, authorTerm, genreIndex, mixTerm, allTrackTerm, artistTerm, composerTerm, tvSeasonTerm, producerTerm, ratingTerm, songTerm, movieArtistTerm, showTerm, movieTerm, albumTerm
callback The name of the Javascript callback function you want to use when returning search results to your website. For example: wsSearchCB. Y, for cross-site searches wsSearchCB
limit The number of search results you want the iTunes Store to return. For example: 25.The default is 50. N 1 to 200
lang 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). N en_us, ja_jp
version The search result key version you want to receive back from your search.The default is 2. N 1, 2
explicit A flag indicating whether or not you want to include explicit content in your search results.The default is Yes. N Yes, No
  • 关键是要正确编码你的URL才能被委托会员链接。在编码原始链接附属票据可以在Advanced Affiliate Linking的文档中找到。
  • 为了提高请求时间,通过指定适当的limit参数,在检索api的时候返回极少数的结果。
  • 大型网站应该建立缓存逻辑,检索查找api的请求。为了说明这一点,请稍后查看本篇文章的Caching Architecture。

以下是具体的搜索请求完全合格的URL的例子:

你也可以创建一个基于iTunes IDs, UPCs/ EANs的搜索请求去商店里面搜索内容。和所有音乐指南(AMG)标识的存储内容。基于ID的查找速度更快,而且含有较少的假阳性结果。

以下是具体的查找请求完全合格的URL的例子:

所有的JSON结果被编码为UTF-8。有关JSON的更多信息,请参阅http://www.json.org

下面的示例显示在iTunes Store的歌曲JSON的结果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{"wrapperType":"track",
"kind":"song",
"artistId":909253,
"collectionId":120954021,
"trackId":120954025,
"artistName":"Jack Johnson",
"collectionName":"Sing-a-Longs and Lullabies for the Film Curious George",
"trackName":"Upside Down",
"collectionCensoredName":"Sing-a-Longs and Lullabies for the Film Curious George",
"trackCensoredName":"Upside Down",
"artistViewUrl":"https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewArtist?id=909253",
"collectionViewUrl":"https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?i=120954025&id=120954021&s=143441",
"trackViewUrl":"https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?i=120954025&id=120954021&s=143441",
"previewUrl":"http://a1099.itunes.apple.com/r10/Music/f9/54/43/mzi.gqvqlvcq.aac.p.m4p",
"artworkUrl60":"http://a1.itunes.apple.com/r10/Music/3b/6a/33/mzi.qzdqwsel.60x60-50.jpg",
"artworkUrl100":"http://a1.itunes.apple.com/r10/Music/3b/6a/33/mzi.qzdqwsel.100x100-75.jpg",
"collectionPrice":10.99,
"trackPrice":0.99,
"collectionExplicitness":"notExplicit",
"trackExplicitness":"notExplicit",
"discCount":1,
"discNumber":1,
"trackCount":14,
"trackNumber":1,
"trackTimeMillis":210743,
"country":"USA",
"currency":"USD",
"primaryGenreName":"Rock"}

下表定义了JSON格式返回结果的键和值:

Result Key Description Returned Return Values and Examples
wrapperType The name of the object returned by the search request. Y track, collection, artistFor example: track.
*explicitness The Recording Industry Association of America (RIAA) parental advisory for the content returned by the search request.For more information, see http://itunes.apple.com/WebObjects/MZStore.woa/wa/parentalAdvisory. Y explicit (explicit lyrics, possibly explicit album cover), cleaned (explicit lyrics “bleeped out”), notExplicit (no explicit lyrics)For example: “trackExplicitness”:”notExplicit”.
kind The kind of content returned by the search request. Y book, album, coached-audio, feature-movie, interactive- booklet, music-video, pdf podcast, podcast-episode, software-package, song, tv- episode, artistFor example: song.
trackName The name of the track, song, video, TV episode, and so on returned by the search request. Y For example: “Banana Pancakes”.
artistName The name of the artist returned by the search request. Y For example: Jack Johnson.
collectionName The name of the album, TV season, audiobook, and so on returned by the search request. Y For example: “In Between Dreams”.
*censoredName The name of the album, TV season, audiobook, and so on returned by the search request, with objectionable words *’d out.Note: Artist names are never censored. Y For example: “S**t Happens”.
artworkUrl100, artworkUrl60 A URL for the artwork associated with the returned media type, sized to 100×100 pixels or 60×60 pixels. Only returned when artwork is available For example: “http:// a1.itunes.apple.com/jp/r10/Music/ y2005/m06/d03/h05/ s05.oazjtxkw.100×100-75.jpg”.
*viewURL A URL for the content associated with the returned media type. You can click the URL to view the content in the iTunes Store. Y For example: “http:// itunes.apple.com/WebObjects/ MZStore.woa/wa/viewAlbum? i=68615807&id=68615813&s=1434 62”.
previewUrl A URL referencing the 30-second preview file for the content associated with the returned media type. . Only returned when media type is track For example: “http:// a392.itunes.apple.com/jp/r10/ Music/y2005/m06/d03/h05/s05.zdzqlufu.p.m4p”.
trackTimeMillis The returned track’s time in milliseconds. Only returned when media type is track

缓存框架

cache-architecture-1.jpg

法律声明

开发人员可以使用某些促销内容,可以通过苹果公司提供,包括歌曲预览和音乐视频,专辑封面,和App图标(“促销内容”),促进了促销内容的主题的目的;提供了这种促销内容:

(一)被放置仅在促进该促销内容是基于内容页面;

(二)是接近了“iTunes下载”,“下载的应用程序商店”或“下载的iBooks商店”标志(如批准苹果公司)充当直接链接到iTunes中或App Store页面,消费者可以购买该宣传内容;

(三)包括归属指示促销内容是“提供了iTunes的礼遇”如果这样的促销内容包括歌曲或音乐视频预览;

(四)仅流,而不是下载,保存,缓存,或者与视频同步,如果这样的促销内容包括歌曲或音乐视频预览;

(五)不用于除了其促销目的独立娱乐价值

(六)不用于促进任何其他商品或服务。开发商承认,苹果提供的促销内容的“原样”,并拒绝任何和所有陈述或担保,包括但不限于非侵权。开发者应将与促销内容到苹果在收到立即连接收到任何索赔,并将根据要求苹果公司立刻删除任何促销内容。

本协议和您的宣传内容使用受加利福尼亚州法律管辖。

Comments

Your browser is out-of-date!

Update your browser to view this website correctly.&npsb;Update my browser now

×