iTunes APIを触る


とあるプロジェクトで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のドキュメント](http://www.apple.com/itunes/affiliates/resources/documentation/itunes-store-web-service-search-api.html#searching)に書いてある。

#### 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の説明(もといメモ)は終わり。