iTunes Search API 翻译

最新推荐文章于 2025-03-02 11:00:06 发布

陈伯君

最新推荐文章于 2025-03-02 11:00:06 发布

阅读量2k

点赞数

分类专栏： iOS-开发文章标签： api app store 搜索 itunes iOS

本文链接：https://blog.csdn.net/a834994897/article/details/52681919

版权

iOS-开发专栏收录该内容

8 篇文章

订阅专栏

概述

这个搜索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.

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.

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.

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.

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.

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.

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).

en_us, ja_jp

version

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

1, 2

explicit

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

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":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

缓存框架

这里写图片描述

法律声明

开发人员可以使用某些促销内容，可以通过苹果公司提供，包括歌曲预览和音乐视频，专辑封面，和App图标（“促销内容”），促进了促销内容的主题的目的;提供了这种促销内容：（一）被放置仅在促进该促销内容是基于内容页面; （二）是接近了“iTunes下载”，“下载的应用程序商店”或“下载的iBooks商店”标志（如批准苹果公司）充当直接链接到iTunes中或App Store页面，消费者可以购买该宣传内容; （三）包括归属指示促销内容是“提供了iTunes的礼遇”如果这样的促销内容包括歌曲或音乐视频预览; （四）仅流，而不是下载，保存，缓存，或者与视频同步，如果这样的促销内容包括歌曲或音乐视频预览; （五）不用于除了其促销目的独立娱乐价值;及（六）不用于促进任何其他商品或服务。开发商承认，苹果提供的促销内容的“原样”，并拒绝任何和所有陈述或担保，包括但不限于非侵权。开发者应将与促销内容到苹果在收到立即连接收到任何索赔，并将根据要求苹果公司立刻删除任何促销内容。

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

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