iTunes APIを触る

More than 5 years have passed since last update.

とあるプロジェクトでiTunes関係のサービスを作るので、APIを触ってみる。


iTunes Store Web Service Search API を使ってアプリ情報を取得する

http://jmblog.jp/archives/798


こちらの記事によると、Appleが標準で提供しているAPIのドキュメントは 古い らしい。


Search API


URI

現在のAPIのURIは、

http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsSearch?[parameters]

こうなっている。


Parameter

パラメーターについては、Appleのドキュメントに書いてある。


term

検索キーワード。URLエンコード必要。必須キー。


country

iTunes Storeの国を指定する。日本だったら JP 。必須。


entity

iTunesで検索できるもの(曲や映画やアプリ)を絞り込むキー。

必須ではない。

movie : movieArtist, movie

music : musicArtist, musicTrack, album, musicVideo, mix, song
podcast : podcastAuthor, podcast
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

この中の一つだけ指定するだけでも、大分検索結果が絞れる。


callback

JSONP。 javascriptでcallback functionを使う場合指定する。

必須ではない。

使えるものはこんなところ。他にもあるけどAppleのドキュメント読んで。


Return

http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsSearch?term=dinka&country=JP&entity=musicTrack

termdinkacountryJPentitymusicTrack にして検索してみる。ちなみにdinkaはアメリカのプログレッシブ・ハウスのクイーン。

返ってきたデータ :

{

"results": [
{
"primaryGenreName": "Dance",
"currency": "JPY",
"country": "JPN",
"trackTimeMillis": 187500,
"trackNumber": 15,
"trackCount": 20,
"discNumber": 1,
"discCount": 1,
"trackExplicitness": "notExplicit",
"collectionExplicitness": "notExplicit",
"releaseDate": "2013-01-02T08:00:00Z",
"trackPrice": 200,
"collectionPrice": 1050,
"artworkUrl100": "http://a1.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.100x100-75.jpg",
"trackName": "Radiate (feat. Julie Thompson)",
"collectionName": "Manhattan Records Presents \"A Night Out\" - EDM Party Music (Mixed By DJ Kent)",
"artistName": "Dinka",
"trackId": 584640299,
"collectionId": 584639988,
"artistId": 268011176,
"kind": "song",
"wrapperType": "track",
"collectionCensoredName": "Manhattan Records Presents \"A Night Out\" - EDM Party Music (Mixed By DJ Kent)",
"trackCensoredName": "Radiate (feat. Julie Thompson)",
"artistViewUrl": "https://itunes.apple.com/jp/artist/dinka/id268011176?uo=4",
"collectionViewUrl": "https://itunes.apple.com/jp/album/radiate-feat.-julie-thompson/id584639988?i=584640299&uo=4",
"trackViewUrl": "https://itunes.apple.com/jp/album/radiate-feat.-julie-thompson/id584639988?i=584640299&uo=4",
"previewUrl": "http://a1762.phobos.apple.com/us/r1000/086/Music/v4/5c/ff/97/5cff97e9-2f86-9e7c-9dd3-da289c9bd712/mzaf_1805109549567810261.aac.m4a",
"artworkUrl30": "http://a3.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.30x30-50.jpg",
"artworkUrl60": "http://a2.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.60x60-50.jpg"
},
{
"primaryGenreName": "Dance",
"currency": "JPY",
"country": "JPN",
"trackTimeMillis": 490382,
"trackNumber": 14,
"trackCount": 40,
"discNumber": 1,
"discCount": 1,
"trackExplicitness": "notExplicit",
"collectionExplicitness": "notExplicit",
"releaseDate": "2010-07-23T07:00:00Z",
"trackPrice": 150,
"collectionPrice": 1500,
"artworkUrl100": "http://a2.mzstatic.com/us/r1000/004/Music/c4/90/f9/mzi.kizpeple.100x100-75.jpg",
"trackName": "Elements (EDX's 5un5hine Remix)",
"collectionName": "Ibiza House Tunes 2010",
"artistName": "Dinka",
"trackId": 381728466,
"collectionId": 381728372,
"artistId": 268011176,
"kind": "song",
"wrapperType": "track",
"collectionCensoredName": "Ibiza House Tunes 2010",
"trackCensoredName": "Elements (EDX's 5un5hine Remix)",
"artistViewUrl": "https://itunes.apple.com/jp/artist/dinka/id268011176?uo=4",
"collectionViewUrl": "https://itunes.apple.com/jp/album/elements-edxs-5un5hine-remix/id381728372?i=381728466&uo=4",
"trackViewUrl": "https://itunes.apple.com/jp/album/elements-edxs-5un5hine-remix/id381728372?i=381728466&uo=4",
"previewUrl": "http://a601.phobos.apple.com/us/r1000/072/Music/v4/7b/96/fa/7b96fa0b-6c99-6402-3517-6b495db76ef8/mzaf_7307640393574451724.aac.m4a",
"artworkUrl30": "http://a1.mzstatic.com/us/r1000/004/Music/c4/90/f9/mzi.kizpeple.30x30-50.jpg",
"artworkUrl60": "http://a3.mzstatic.com/us/r1000/004/Music/c4/90/f9/mzi.kizpeple.60x60-50.jpg"
}, (ずっと続く)


Analyze return data

{results: [JSONオブジェクト] }

結果は results というキーにJSONオブジェクトの配列で返される。

返されるJSONオブジェクトの中身 :

{

"primaryGenreName": "Dance",
"currency": "JPY",
"country": "JPN",
"trackTimeMillis": 187500,
"trackNumber": 15,
"trackCount": 20,
"discNumber": 1,
"discCount": 1,
"trackExplicitness": "notExplicit",
"collectionExplicitness": "notExplicit",
"releaseDate": "2013-01-02T08:00:00Z",
"trackPrice": 200,
"collectionPrice": 1050,
"artworkUrl100": "http://a1.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.100x100-75.jpg",
"trackName": "Radiate (feat. Julie Thompson)",
"collectionName": "Manhattan Records Presents \"A Night Out\" - EDM Party Music (Mixed By DJ Kent)",
"artistName": "Dinka",
"trackId": 584640299,
"collectionId": 584639988,
"artistId": 268011176,
"kind": "song",
"wrapperType": "track",
"collectionCensoredName": "Manhattan Records Presents \"A Night Out\" - EDM Party Music (Mixed By DJ Kent)",
"trackCensoredName": "Radiate (feat. Julie Thompson)",
"artistViewUrl": "https://itunes.apple.com/jp/artist/dinka/id268011176?uo=4",
"collectionViewUrl": "https://itunes.apple.com/jp/album/radiate-feat.-julie-thompson/id584639988?i=584640299&uo=4",
"trackViewUrl": "https://itunes.apple.com/jp/album/radiate-feat.-julie-thompson/id584639988?i=584640299&uo=4",
"previewUrl": "http://a1762.phobos.apple.com/us/r1000/086/Music/v4/5c/ff/97/5cff97e9-2f86-9e7c-9dd3-da289c9bd712/mzaf_1805109549567810261.aac.m4a",
"artworkUrl30": "http://a3.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.30x30-50.jpg",
"artworkUrl60": "http://a2.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.60x60-50.jpg"
}

全部を説明するのは面倒なので一部だけ説明する。


primaryGenreName

ジャンルの名前。


trackPrice

楽曲の金額


artworkUrl100, artworkUrl130, artworkUrl160

楽曲のアートワークのURLとサイズ。


collectionName

アルバムやオーディオブックの名前。


trackName

楽曲の名前。


trackViewUrl

楽曲のiTunesストアのURL。


trackId

iTunesで管理してる楽曲のID。

だいたいこのようなかたちで検索結果が返される。


Lookup API

楽曲の trackId がわかると、iTunes Storeの Lookup API が使用可能になる。


URI

http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsLookup?[parameters]


Parameters

だいたいSearch APIと同じだが、 Lookup APiのパラメーターには、かならず id パラメーターが必要となる*

id は上記のSearchAPIの結果だとtrackIdを持ってくる。


Return

id パラメーターに trackId のデータを入れ、 country データも入れる。

http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsLookup?id=584640299&country=JP

返ってくるデータ :

{

"primaryGenreName": "Dance",
"currency": "JPY",
"country": "JPN",
"trackTimeMillis": 187500,
"trackNumber": 15,
"trackCount": 20,
"discNumber": 1,
"discCount": 1,
"trackExplicitness": "notExplicit",
"collectionExplicitness": "notExplicit",
"releaseDate": "2013-01-02T08:00:00Z",
"trackPrice": 200,
"collectionPrice": 1050,
"artworkUrl100": "http://a1.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.100x100-75.jpg",
"trackName": "Radiate (feat. Julie Thompson)",
"collectionName": "Manhattan Records Presents \"A Night Out\" - EDM Party Music (Mixed By DJ Kent)",
"artistName": "Dinka",
"trackId": 584640299,
"collectionId": 584639988,
"artistId": 268011176,
"kind": "song",
"wrapperType": "track",
"collectionCensoredName": "Manhattan Records Presents \"A Night Out\" - EDM Party Music (Mixed By DJ Kent)",
"trackCensoredName": "Radiate (feat. Julie Thompson)",
"artistViewUrl": "https://itunes.apple.com/jp/artist/dinka/id268011176?uo=4",
"collectionViewUrl": "https://itunes.apple.com/jp/album/radiate-feat.-julie-thompson/id584639988?i=584640299&uo=4",
"trackViewUrl": "https://itunes.apple.com/jp/album/radiate-feat.-julie-thompson/id584639988?i=584640299&uo=4",
"previewUrl": "http://a1762.phobos.apple.com/us/r1000/086/Music/v4/5c/ff/97/5cff97e9-2f86-9e7c-9dd3-da289c9bd712/mzaf_1805109549567810261.aac.m4a",
"artworkUrl30": "http://a3.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.30x30-50.jpg",
"artworkUrl60": "http://a2.mzstatic.com/us/r1000/062/Music/v4/90/3f/c8/903fc88b-1552-48a3-f7d8-8f690e4bb94f/2400fixEDMitunes.60x60-50.jpg"
}

ちなみに、このLookup APIも results キーにJSONオブジェクトが入っている配列という形で返ってくる。その中身が上。

中身を見ると、SearchAPIで返ってきたデータとほぼ同じ。


重要なこと

これらのAPIで返ってくるデータに trackViewUrl とか、URLに関するデータがあるが、このURLを そのまま開くとWeb上でtrackを見ることができる が、 itunes:// というプロトコルをつけると、 iTunes上で表示される。*

これでひと通りiTunesAPIの説明(もといメモ)は終わり。