iTunes Search API

发表于 | 分类于 | | 阅读次数 |

概述

这个搜索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里面的内容：

火狐截图_2016-09-27T08-16-07.243Z.png
ps:实在不会用markdown来实现表格套表格。。。。

内容

  • 关键是要正确编码你的URL才能被委托会员链接。在编码原始链接附属票据可以在Advanced Affiliate Linking的文档中找到。
  • 为了提高请求时间，通过指定适当的limit参数，在检索api的时候返回极少数的结果。
  • 大型网站应该建立缓存逻辑，检索查找api的请求。为了说明这一点，请稍后查看本篇文章的Caching Architecture。

搜索例子

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

检索例子

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

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

了解搜索结果

你搜索的结果用JSON格式返回，JSON有两种结构：

  • 一种key/value的集合。也可以称之为一种对象，这个概念类似于Java Map对象，一个Javascript字典，或Pearl/ Ruby的哈希值。对象是一个无序的名称/值对，用左括号开始（{）和一个右括号结束（}）。每个名称由双引号包围，后跟一个冒号（:)）;名称/值对用逗号（，）隔开。
  • 值的有序列表，也称为阵列。数组是值的有序集合，用左括号开头（[），并以右括号结束（]）。值用逗号（，）分隔。

所有的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
{"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格式返回结果的键和值：

key 描述 是否返回 返回值以及例子
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的礼遇”如果这样的促销内容包括歌曲或音乐视频预览; （四）仅流，而不是下载，保存，缓存，或者与视频同步，如果这样的促销内容包括歌曲或音乐视频预览; （五）不用于除了其促销目的独立娱乐价值;及（六）不用于促进任何其他商品或服务。开发商承认，苹果提供的促销内容的“原样”，并拒绝任何和所有陈述或担保，包括但不限于非侵权。开发者应将与促销内容到苹果在收到立即连接收到任何索赔，并将根据要求苹果公司立刻删除任何促销内容。

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

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