iTunes Search API 翻譯

目錄

• 概述
• 搜尋 iTunes Store
• 内容
• 搜尋例子
• 檢索例子
• 了解搜尋結果
• 緩存架構
• 法律聲明

概述

這個搜尋API允許你通過關鍵詞在你的網站上搜尋iTunes Store，App Store, iBooks Store and Mac App Store。你可以搜尋各種内容；包括應用、圖書、電影、廣播、音樂、視訊、有聲讀物以及TV節目。你也可以調用一個實名查詢請求來建立内容庫之間的映射和數字目錄。開發者可以使用API裡的推廣的内容，包括歌曲預覽，音樂錄像，專輯封面和APP圖示隻用在推廣的店面，不用于娛樂用途。從API裡使用音樂樣本及其他必須和店面徽章相似。條款和條件适用。

這項計劃允許當你的網站或者app獲得點選後獲得一些傭金。該項計劃更多資訊請檢視：http://www.apple.com/itunes/affiliates。

搜尋 iTunes Store

通過web去查找并且顯示結果在web網站上。你必須建立一個搜尋區域，通過完全限定的URL請求iTunes Store，并從傳回的結果中解析JSON。然後将結果顯示在web上。

完整的網址必須有以下格式：

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

在參數裡有一個或多個鍵值對，來詳細說明你傳回的結果。

構造一個參數鍵值對，你必須将每個參數的key等于（=）一個字元串value。例如：key1 =value1。建立一個字元串鍵值對，你必須将每對鍵值對用與（&）符号連結。例如:key1=value1&key2=value2&key3=value3

注：當您為網站建立搜尋域和腳本時，你應該使用動态腳本标簽你的XMLHTTP腳本調用請求。例如:

<script src="https://.../search?parameterkeyvalue&callback="{name of JavaScript function in webpage}"/>
           

您可以使用下表定義的參數的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: movie movieArtist, movie podcast podcastAuthor, podcast music musicArtist, musicTrack, album, musicVideo, mix, song Please note that “musicTrack” can include both songs and music videos in the results musicVideo musicArtist, musicVideo audiobook audiobookAuthor, audiobook shortFilm shortFilmArtist, shortFilm tvShow tvEpisode, tvSeason software software, iPadSoftware, macSoftware ebook ebook all movie, 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: movie actorTerm, genreIndex, artistTerm, shortFilmTerm, producerTerm, ratingTerm, directorTerm, releaseYearTerm, featureFilmTerm, movieArtistTerm, movieTerm, ratingIndex, descriptionTerm podcast titleTerm, languageTerm, authorTerm, genreIndex, artistTerm, ratingIndex, keywordsTerm, descriptionTerm music mixTerm, genreIndex, artistTerm, composerTerm, albumTerm, ratingIndex, songTerm musicVideo genreIndex, artistTerm, albumTerm, ratingIndex, songTerm audiobook titleTerm, authorTerm, genreIndex, ratingIndex shortFilm genreIndex, artistTerm, shortFilmTerm, ratingIndex, descriptionTerm software softwareDeveloper tvShow genreIndex, tvEpisodeTerm, showTerm, tvSeasonTerm, ratingIndex, descriptionTerm all actorTerm, 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的例子：

* 要搜尋所有傑克·約翰遜的音頻和視訊内容（電影，播客，音樂，音樂視訊，有聲讀物，電影短片和電視節目），您的網址将如下所示：

https://itunes.apple.com/search?term=jack+johnson

* 要搜尋所有傑克·約翰遜的音頻和視訊内容（電影，播客，音樂，音樂視訊，有聲讀物，電影短片和電視節目），并且隻傳回前25條。您的網址将如下所示：

https://itunes.apple.com/search?term=jack+johnson&limit=25

* 要檢索傑克·約翰遜的音頻，您的網址将如下所示：

https://itunes.apple.com/search?term=jack+johnson&entity=musicVideo

* 要搜尋所有吉姆·瓊斯音頻和視訊内容，并傳回隻從加拿大iTunes商店的結果，您的網址将如下所示：

https://itunes.apple.com/search?term=jim+jones&country=ca

* 要搜尋名為“Yelp的”應用程式和來自美國的iTunes商店隻傳回的結果，您的網址将如下所示：

https://itunes.apple.com/search?term=yelp&country=us&entity=software

檢索例子

你也可以建立一個基于iTunes IDs, UPCs/ EANs的搜尋請求去商店裡面搜尋内容。和所有音樂指南（AMG）辨別的存儲内容。基于ID的查找速度更快，而且含有較少的假陽性結果。

以下是具體的查找請求完全合格的URL的例子：

• 通過iTunes藝術家ID查找傑克·約翰遜：

  [https://itunes.apple.com/lookup?id=909253](https://itunes.apple.com/lookup?id=909253

  )

• 通過iTunes ID查找Yelp的軟體應用程式：

  https://itunes.apple.com/lookup?id=284910350

• 通過AMG藝術家ID查找傑克·約翰遜：

  https://itunes.apple.com/lookup?amgArtistId=468749

• 通過AMG藝術家的ID查找多個藝術家：

  https://itunes.apple.com/lookup?amgArtistId=468749,5723

• 查找的傑克·約翰遜的所有專輯：

  https://itunes.apple.com/lookup?id=909253&entity=album

• 其AMG藝術家的ID查找多個藝術家和獲得每個藝術家的前5張專輯：

  https://itunes.apple.com/lookup?amgArtistId=468749,5723&entity=album&limit=5

• 通過AMG藝術家的ID查找多個藝術家和獲得每個藝術家的5最新歌曲：

  https://itunes.apple.com/lookup?amgArtistId=468749,5723&entity=song&limit=5&sort=recent

• 通過UPC查找一個專輯或視訊：

  [https://itunes.apple.com/lookup?upc=720642462928](https://itunes.apple.com/lookup?upc=720642462928

  )

• 通過UPC查找專輯，包括這張專輯的曲目：

  https://itunes.apple.com/lookup?upc=720642462928&entity=song

• 通過專輯ID來查找一個專輯：

  [https://itunes.apple.com/lookup?amgAlbumId=15175,15176,15177,15178,15183,15184,15187,1519,15191,15195,15197,15198](https://itunes.apple.com/lookup?amgAlbumId=15175,15176,15177,15178,15183,15184,15187,1519,15191,15195,15197,15198

  )

• 通過AMG視訊ID查找一部電影：

  https://itunes.apple.com/lookup?amgVideoId=17120

• 通過13位ISBN查找一本書：

  https://itunes.apple.com/lookup?isbn=9780316069359

了解搜尋結果

你搜尋的結果用JSON格式傳回，JSON有兩種結構：

* 一種key/value的集合。也可以稱之為一種對象，這個概念類似于Java Map對象，一個Javascript字典，或Pearl/ Ruby的哈希值。對象是一個無序的名稱/值對，用左括号開始（{）和一個右括号結束（}）。每個名稱由雙引号包圍，後跟一個冒号（:)）;名稱/值對用逗号（，）隔開。

* 值的有序清單，也稱為陣列。數組是值的有序集合，用左括号開頭（[），并以右括号結束（]）。值用逗号（，）分隔。

所有的JSON結果被編碼為UTF-8。有關JSON的更多資訊，請參閱http://www.json.org。

下面的示例顯示在iTunes Store的歌曲JSON的結果

{"wrapperType":"track",
 "kind":"song",
 "artistId":,
 "collectionId":,
 "trackId":,
 "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":,
 "trackPrice":,
 "collectionExplicitness":"notExplicit",
 "trackExplicitness":"notExplicit",
 "discCount":,
 "discNumber":,
 "trackCount":,
 "trackNumber":,
 "trackTimeMillis":,
 "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

緩存架構

法律聲明

開發人員可以使用某些促銷内容，可以通過蘋果公司提供，包括歌曲預覽和音樂視訊，專輯封面，和App圖示（“促銷内容”），促進了促銷内容的主題的目的;提供了這種促銷内容：（一）被放置僅在促進該促銷内容是基于内容頁面; （二）是接近了“iTunes下載下傳”，“下載下傳的應用程式商店”或“下載下傳的iBooks商店”标志（如準許蘋果公司）充當直接連結到iTunes中或App Store頁面，消費者可以購買該宣傳内容; （三）包括歸屬訓示促銷内容是“提供了iTunes的禮遇”如果這樣的促銷内容包括歌曲或音樂視訊預覽; （四）僅流，而不是下載下傳，儲存，緩存，或者與視訊同步，如果這樣的促銷内容包括歌曲或音樂視訊預覽; （五）不用于除了其促銷目的獨立娛樂價值;及（六）不用于促進任何其他商品或服務。開發商承認，蘋果提供的促銷内容的“原樣”，并拒絕任何和所有陳述或擔保，包括但不限于非侵權。開發者應将與促銷内容到蘋果在收到立即連接配接收到任何索賠，并将根據要求蘋果公司立刻删除任何促銷内容。

本協定和您的宣傳内容使用受加利福尼亞州法律管轄。

原文位址：http://www.apple.com/itunes/affiliates/resources/documentation/itunes-store-web-service-search-api.html