目次


はじめに

Search API を使えば、iTunes Store、App Store、 iBookstore、Mac App Store のコンテンツを検索するためのフィールドをご自分のウェブサイトに載せることができます。App、電子書籍、映画、Podcast、音楽、ミュージックビ デオ、オーディオブック、テレビ番組など、さまざまなコンテンツの検索が可能です。また、ID ベースのルックアップリクエストを呼び出し、自分のコンテンツライブラリとデジタルカタログのマッピングを作成できます。利用規約が適用されます。

アフィリエイトプログラムは、自分のウェブサイトや App でのクリックを通して iTunes Store、App Store、iBookstore、Mac App Store で発生した収益に基づき、コミッション (報酬) を獲得できるプログラムです。アフィリエイトプログラムの詳細情報については、 http://www.apple.com/itunes/affiliatesをご覧ください。

検索

自分のウェブサイトのフィールドからコンテンツを検索し、その結果がウェブサイトに表示されるようにするには、iTunes Store に完全修飾 URL コンテンツリクエストを渡す検索フィールドを作成し、検索によって返された JSON ( JavaScript Object Notation) フォーマットを解析し、結果をウェブサイトに表示する必要があります。

完全修飾 URL は必ず次の形式で指定します。

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

parameterkeyvalue には、クエリの詳細を示すパラメータキー/値ペアを 1 つ以上含めることができます。

パラメータキー/値ペアを作成するには、各パラメータキーを値の文字列と等号 (=) で連結します。たとえば次のようになります。key1=value1。複数のパラメータキー/値ペアを作成するには、アンパサンド (&) を使って各ペアを連結します。たとえば次のようになります。

key1=value1&key2=value2&key3=value3

注意: ご自分のウェブサイト用に検索フィールドとスクリプトを作成するとき、XMLHttp スクリプト呼び出しリクエストに動的スクリプトタグを使ってください。たとえば次のようになります。

script src=”https://…/search?parameterkeyvalue&callback=”{ウェブページ内の JavaScript 関数の名前}”

次の表に、iTunes Store、App Store、iBookstore、Mac App Store のコンテンツの検索で指定できるパラメータキーと値の定義を示します。

パラメータキー 説明 必須
term URL エンコード済みの検索条件文字列。例: jack+johnson 必須 任意の URL エンコード済み文字列。

注意: URL エンコーディングでは、スペースがプラス (+) 記号に変換され、英数字、ピリオド (.)、ダッシュ (-)、アンダースコア (_)、アスタリスク (*) を除くすべての文字がエンコードされます。

country 検索したい Store の2文字の国コード。検索では、指定した国のデフォルトの Store が使われます。例: US

デフォルトの値は US です。

必須 ISO国コードの一覧については、 を参照してください。
media 検索したいメディアタイプ。例: movie(映画)

デフォルトの値は all です。

任意 movie, podcast, music, musicVideo, audiobook, shortFilm, tvShow, software, ebook, all
entity 返したい検索のタイプ。指定したメディアタイプに基づく。例: movieArtist (メディアタイプ movie で検索する場合)

デフォルトの値は、指定したメディアタイプに関連するトラックエンティティです。

任意 以下は、メディアタイプ別の利用可能なエンティティです。

movie movieArtist, movie
podcast podcastAuthor, podcast
music musicArtist, musicTrack, album, musicVideo, mix, song
“musicTrack” では、曲とミュージックビデオの両方が結果に含まれる可能性があります。
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 Store で検索したい属性。指定したメディアタイプに基づく。たとえば、アーティストを名前で検索したい場合は、entity=allArtist&attribute=allArtistTerm と指定します。

この例で、term=maroon を指定して検索すると、iTunes は検索結果として、タイトルに “maroon” という語が含まれた曲をレコーディングしたことのあるすべてのアーティストを返す代わりに、”Maroon 5″ を返します。

デフォルトの値は、指定したメディアタイプに関連するすべての属性です。

任意 以下は、メディアタイプ別の利用可能な属性です。

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 ウェブサイトに検索結果を返すときに使う Javascript コールバック関数の名前。例: wsSearchCB 必須 (クロスサイト検索の場合) wsSearchCB
limit iTunes Store から返される検索結果の数。例: 25

デフォルトの値は 50 です。

任意 1 ~ 200
lang 検索結果を返すときに使う言語 (英語または日本語)。5 文字のコード名を使って言語を指定します。例: en_us

デフォルトの値は en_us (英語) です。

任意 en_us, ja_jp
version 検索で受け取る検索結果キーのバージョン。

デフォルトの値は 2 です。

任意 1, 2
explicit 検索結果に露骨な内容を含めるかどうかを示すフラグ。

デフォルトの値は Yes です。

任意 Yes, No
注意事項
  • アフィリエイトリンクでコミッションを獲得できるよう、URL を正しくエンコードすることが重要です。生リンクをアフィリエイト用にエンコードする際の注意事項が、 Advanced Affiliate Linking ドキュメントに記載されています。
  • 応答時間を向上させるには、limit パラメータキーに適切な値を指定して、Search API によって返される検索結果の数を最小限に抑えてください。
  • 大規模なウェブサイトでは、Search API に送信する検索やルックアップのリクエストに対してキャッシュロジックを設定してください。具体例については、このドキュメントの後半にある「キャッシュアーキテクチャ」を参照してください。
検索の例

次に挙げるのは、特定の検索リクエストに対する完全修飾 URL の例です。

ルックアップの例

Store のコンテンツを検索する際、iTunes ID、UPC/EAN、および All Music Guide (AMG) ID に基づいてコンテンツを検索するルックアップリクエストを作成することもできます。ID ベースのルックアップを使うと、検索時間が短縮され、誤判定も少なくなります。

次に挙げるのは、特定のルックアップリクエストに対する完全修飾 URL の例です。

検索結果について

Search API では、JSON (JavaScript Object Notation) フォーマットで検索結果が返されます。JSON は、次の 2 つの構造体から構成されています。

  • 名前/値のペアの集合体。オブジェクトととも呼ばれます。この概念は、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 の結果キーと値の定義を示します。

結果キー 説明 返されるかどうか 返された値と例
wrapperType 検索リクエストで返されたオブジェクトの名前。 はい track, collection, artist

例: track

*explicitness 検索リクエストで返されたコンテンツに対するアメリカレコード協会 (RIAA) のペアレンタルアドバイザリー。

詳細情報については、http://itunes.apple.com/WebObjects/MZStore.woa/wa/parentalAdvisory を参照してください。

はい explicit (露骨な歌詞、露骨と思われるアルバムジャケット)、cleaned (露骨な歌詞がピーという音で消されている)、notExplicit (露骨な歌詞なし)

例: “trackExplicitness”:”notExplicit”

kind 検索リクエストで返されたコンテンツの種類。 はい book, album, coached-audio, feature-movie, interactive- booklet, music-video, pdf podcast, podcast-episode, software-package, song, tv- episode, artist

例: song

trackName 検索リクエストで返されたトラック、曲、ビデオ、テレビエピソードなどの名前。 はい 例: “Banana Pancakes”
artistName 検索リクエストで返されたアーティスト名。 はい 例: Jack Johnson
collectionName 検索リクエストで返されたアルバム、テレビシーズン、オーディオブックなどの名前。 はい 例: “In Between Dreams”
*censoredName 検索リクエストで返されたアルバム、テレビシーズン、オーディオブックなどの名前。不適切な言葉が * で消されている。

注意: アーティスト名は伏せ字にはなりません。

はい 例: “S**t Happens”
artworkUrl100, artworkUrl60 返されたメディアタイプに関連するアートワークの URL。アートワークのサイズは 100×100 ピクセルまたは 60×60 ピクセルに調整される。 アートワークが提供されている場合にのみ返される 例: “http:// a1.itunes.apple.com/jp/r10/Music/ y2005/m06/d03/h05/ s05.oazjtxkw.100×100-75.jpg”
*viewURL 返されたメディアタイプに関連するコンテンツの URL。URL をクリックすると、iTunes Store 内のコンテンツが表示される。 はい 例: “http:// itunes.apple.com/WebObjects/ MZStore.woa/wa/viewAlbum? i=68615807&id=68615813&s=1434 62”
previewUrl 返されたメディアタイプに関連するコンテンツの 30 秒分のプレビューファイルを参照する URL。 メディアタイプが track の場合にのみ返される。 例: “http:// a392.itunes.apple.com/jp/r10/ Music/y2005/m06/d03/h05/s05.zdzqlufu.p.m4p”
trackTimeMillis 返されたトラックの時間 (ミリ秒)。 メディアタイプが track の場合にのみ返される。

キャッシュアーキテクチャ

cache-architecture.jpg

法的要件

アフィリエイトは、Apple が提供する曲や音楽ビデオの試聴、アルバムアート、App アイコンといったプロモーション用コンテンツ (以下「プロモコンテンツ」とします) を、プロモコンテンツの対象を宣伝する目的で使用することができます。ただしプロモコンテンツは下記の条件を満たす必要があります。 (i) プロモコンテンツの対象となるコンテンツを宣伝するためのページにのみ配置すること。(ii) 宣伝されたコンテンツを購入できる iTune または App Store 内のページに直接リンクするため、Apple が承認した「iTunes からダウンロード」または「App Store で配信中」バッジを指定されたとおりにプロモコンテンツのそばに配置すること。(iii) プロモコンテンツに曲や音楽ビデオの試聴/視聴が含まれる場合、プロモコンテンツが「provided courtesy of iTunes (iTunes により無料提供された)」ことを示す文言を添えること。(iv) プロモコンテンツに曲または音楽ビデオの試聴が含まれる場合、ストリーム配信による提供のみとし、曲またはビデオがダウンロード、保存、キャッシュ、また は同期されないようにすること。(v) 宣伝目的から外れた、別のエンターテイメント的価値のある目的のために使用しないこと。(vi) 他の商品やサービスの宣伝に使用しないこと。またアフィリエイトは、Apple がプロモコンテンツを「現状」で提供し、機能、品質、その他一切のコンテンツに関する保証をしない事を了承するものとします。アフィリエイトは、プロモコ ンテンツに関連して何らかの申し立てを受領した場合は直ちに Apple に転送し、Apple が要求した場合は直ちにプロモコンテンツを削除することとします。

本契約およびアフィリエイトによるプロモコンテンツの使用はカリフォルニア州法の元に行われます。