とあるプロジェクトで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
term を dinka 、 country を JP 、 entity を musicTrack にして検索してみる。ちなみに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の説明(もといメモ)は終わり。